REST API Design: Should the update (PUT) request include the ID in the resource URL?

Question

When designing a REST API for update request. Usually PUT is used. Question: should the resource URL include the id usually?

For instance, there is a book resource: http://localhost:8080/library/book When updating a given book with Id, say 123, we could send a PUT request with JSON as the HTTP request body as the update resource. The URL can include the id of the book, e.g. http://localhost:8080/library/book/123 But is this OK? or should we always avoid giving the id in the URL for update request?

Answer 1

When designing a REST API for update request. Usually PUT is used. Question: should the resource URL include the id usually?

The target URI of the PUT request should match the target URI of the GET request used to retrieve a representation of the same resource.

GET /a86e4776-699e-428a-b1a8-5c2828910d86

200 OK
Content-Type: text/plain

Helo World

PUT /a86e4776-699e-428a-b1a8-5c2828910d86
Content-Type: text/plain

Hello World

Therefore, including an "id" in the URI for a PUT request follows precisely the same rules as including an "id" in the URI for a GET request.

The same is true, of course, for POST, PATCH, DELETE, HEAD, etc. The resource identifier identifies the resource.

Now, your local spelling conventions may say that resource identifiers can include identifiers, or not, or only obfuscated identifiers, or whatever. Those kinds of design decisions are local to you, and will be motivated by the kinds of things that are most important to you (ex: we want to make things easy for the operators who need to read our access logs).

---

Reviewing Webber, 2011 may help clarify

HTTP is an application protocol, whose application domain is the transfer of documents over a network.

Answer 2

An URI identifies a resource. A PUT request is supposed to create or replace the representation of that resource. So, if you want to replace the state of book 123, you should PUT /book/123. Think of PUT as uploading an entire file, but you have to give the target “filename”. There is a strong expectation that if you do a PUT /url and later GET /url, you'd get back an equivalent representation to what you've uploaded. This indicates that PUT /book would be incorrect since a later GET /book probably wouldn't return the data you've just uploaded about book 123.

If you want to perform a partial update of a book's state, use a PATCH request. This too would generally require the resource's ID in the URI.

If you want the endpoint to perform some other action, consider a POST request. For example POST /book might use the body of the request to figure out which resources should be affected. If you're not sure which HTTP request method to use but if you want the server to do something (possibly with side effects), then POST is a good default. POST is most commonly used for form submissions, but it's also often used for creating new resources if the server should assign the ID.

Recommended further reading: HTTP request methods on MDN and Request Methods in RFC 7231.

Answer 3

No.

If you are updating resource you will be sending the whole resource in the body, and this will include the Id.

So sending it twice is unnecessary at best and introduces an error (if there is a mismatch) at worst.

Amon and Voice of Unreason, object that the URI = the resource that the put must replace. But I would argue that this is an overly strict interpretation, which is only applicable where the id is the filename.

After all, in such a case you would have to replace book 1 with book 2 if you sent id 2 in the content. Also the equivalent POST documentation insists the only difference is the idempotency of the request, but is happy to have a single url for different documents.

Say you programmed both solutions. The strict interpretation would require a check that both ids matched, whereas my practical interpretation would not. My solution would use less electricity and be faster, cheaper to run and throw less errors.