When serving responses from a REST API with the hypermedia constraint, how to indicate to client which HTTP method(verb) to use?

I think I have a pretty good grasp on the tenets of a RESTful architecture but I'm not there yet.

The part that I can't seem to figure out is how do the clients become aware of which HTTP methods are available to each resource? What about when a specific action is required in the application flow to continue a process?

Simplified Example:

Assuming a client places a simple order to my REST API.

The client will make a post request to: http://api.mycompany.com/orders

Request Payload

<order>
    <items>
        <sku>12345</sku>
        <quantity>1</quantity>
    </items>
</order>

Assuming the request is successful

Response Payload

<order>
    <id>156</id>
    <status>Pending Payment</status>
    <items>
        <sku>12345</sku>
        <quantity>1</quantity>
    </items>    
    <links>
        <link rel="order" url="http://api.mycompany.com/orders/156" />
        <link rel="invoice" url="http://api.mycompany.com/payments/156" />
        <link rel="payment" url="http://api.mycompany.com/invoices/156" />
    </links>
</order>

If I understand the hypermedia constraint correctly, I provide corresponding resources and the client can choose where to go from there.

开发者_Go百科

In the above example the link with rel="order" could be a GET, PUT, or DELETE request. The link with rel="invoice" is restricted to a GET request. The link with rel="payment" will only accept a POST request.

How does the client know this? I know if they make an OPTIONS request to one of the aforementioned resources it should give them the methods that are available but I'm not sure if that's the standard way of handling this kind of scenario.

Any help would be greatly appreciated.

---

The simple fact is that those verbs will be documented in the documentation of the resources.

The question you didn't ask is, "How does a client know what the refs 'order', 'invoice', and 'payment' are for?".

Yet, they suffer the same problem you're asking. And they, too, need to be documented as well.

When those are documented, when those rels are explained as to what they are, why they exist, and what you as a resource consumer would use them for, then the actual verbs necessary to leverage those resources would be documented with them as well.

---

Clients can call any of the HTTP verbs on any URI you expose. Whether or not those actions will have any effect is a separate question.

Clients could discover which methods will work on a particular URI in different ways:

1. They call each URI with the different actions and dynamically figure out which ones work (returning a 2xx response code) and which ones return 405 - Method Not Allowed.
2. The client programmer reads your documentation and codes up the interactions ahead of time.

I'll be honest, I've never seen #1 implemented in a production system. #2 is what makes most sense to me and most humans that have to write clients that consume a REST API.

Note that there is more to consuming a REST API than just knowing which HTTP verb to use. The content and structure of the media type (for both requests and responses) is just as important to document and make available to those who plan to code against your system.