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

Question

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.

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.

Answer 1

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.