RESTful way to accept a choice

Question

I have a simple api, that works like this:

1. A user creates a request ( POST /requests)
2. Another user retrieves all requests ( GET /requests)
3. Then adds an offer to a request ( POST /requests/123/offers)
4. Original user can now see all the offers being made for the request (GET /requests/123/offers)

What i want to do, is allow the inital user to accept an request, but I can't figure out the best way to do it RESTfuly.

Should I do it with the PATCH verb? Like PATCH /requests/123 and require that the patch body contain a valid offer id?

Answer 1

Accepting an offer five times should have the same effect as accepting it once. It is idempotent. So it should be a PUT.

You might want to consider choosing a different name for your "requests." When I do GET /requests/123, I request a response that is a request? This could be a little confusing for clients.

Additionally, try to avoid nesting your resource identifiers. That can create problems for you later. An offer doesn't really have to be "underneath" the corresponding request. What happens when you later want to have offers corresponding to multiple requests?

A good rule of thumb is, if you would consider "Gizmo" an entity in an entity-relationship model, it should be a root-level URI, like in GET /gizmos/17, not GET /widgets/54/gizmos/17. A common mistake is to say "Every Gizmo has exactly one related Widget, so I should nest Gizmo URIs as extensions of Widget URIs."

Below I have a suggestion for how the operations would look. You may want to replace some of the ID references with URIs instead, but that's up to you.

POST /requests            --->   201 Created
                                 Location: /requests/123

GET /requests             --->   200 OK
                                 [
                                     {
                                         "requestId": 123,
                                         "offersUri": "/offers?requestId=123",
                                         ...
                                     },
                                     ...
                                 ]

POST /offers              --->   201 Created
{                                Location: /offers/456
    "requestId": 123,
    "amount": 300,
    ...
}

GET /offers?requestId=123 --->   200 OK
                                 [
                                     {
                                         "requestId": 123,
                                         "amount": 300,
                                         ...
                                     }
                                 ]

PUT /offers/456/approval   --->  204 No Content
PUT /offers/456/approval   --->  204 No Content
PUT /offers/456/approval   --->  204 No Content