I was reading some documents about the appropriate use of URI's using rest services and I came across an example for basic GET .. DELETE requests.

The example uri's were:

Get all users

GET http://mydomain.org/api/users

Get specific user

GET http://mydomain.org/api/users/1

Update user

PUT http://mydomain.org/api/users/1


DELETE http://mydomain.org/api/users/1

A user resource would be either JSON or XML in the form of:

    Id: 1,
    FirstName: 'John',
    LastName: 'Doe'

My question is this. To maintain REST principles, is it required to include the id of the resource within the URI for PUT requests?



You want to PUT a resource to the same URI you intend to GET it from.

RFC 72314.3.4 PUT

  • That makes sense. My assumption was that the id would always be provided with the resource, but I guess that won't always be the case. – Joshua Dale Feb 13 '12 at 19:23
  • 2
    And indeed, if you start using URI's in your interface, you might soon find it useful to remove the id from the resource representation itself. – fumanchu Feb 14 '12 at 1:21
  • 2
    RFC-2616 is obsoleted by RFC-7231 – prasanthv Jun 2 '15 at 17:34
  • @prasanthv what do you mean, did anything change regarding PUT? I don't think so. – Konrad Sep 6 '18 at 7:51

I was going to ask a similar question, but I think I found the answer. I am not sure if it is by REST principles, but here is why it would be bad not to include ID in the URI. So say your PUT is like:

PUT http://mydomain.org/api/users

And then you happen to update multiple users with different id's but the same URI cause there is no ID in your URI. Then, an important thing to know here is that PUT is idempotent http verb. This means that calling it once should have the same effect as calling it mulitple times. Therefore, some intermediate node in the network, just following the fact that you PUT multiple times, might ignore all but one of your requests cause they have the same URI. Finally, that's definetely not what you want cause the intention was to update multiple users not only one.

  • 4
    I doubt this is possible since the body would be different. Even if you were updating the same resource, you could have different updates (with different values) to it and ignoring some of them is a really unexpected behaviour. – falconizer Sep 15 '16 at 8:11
  • An idempotent verb should have the same effect regardless of how many times it was invoked. That's mandated by the standard. – Огњен Шобајић Mar 23 '17 at 22:01
  • 1
    Огњен Шобајић, this can be true only if the request is exactly the same. Lets say we have two requests PUT: /api/users/1, with bodies {"name":"Foo"} and {"name":"Bar"}. Being idempotent doesn't mean that the second request would be ignored, right? It just means that perfoming the exact same request would have the same effect as performing it only once. – Thiago Barcala Apr 20 '17 at 9:23
  • "Being idempotent verb doesn't mean that second request would be ignored" - yes, that's correct. But it may! It is on the intermediate node in the network to decide if it's going to pass through the second PUT request with the same URI. The HTTP standard allows for ignoring the previous requests with the same URI in some cases (e.g. traffic congestion). I believe that it is URI that matters, not the whole request with body. – Огњен Шобајић Oct 11 '18 at 21:21

PUT http://example.com/api/users + body behaves like the put of a map with the key http://example.com/api/users and the value the body. A new entry is created if none exists, else the existing one is overridden.

Question: what is the resource behind http://example.com/api/users ?

Answer: the same than the one provided by GET http://example.com/api/users, the list of all users.

So, the command PUT http://example.com/api/users means that you replace the list of all users with the one you provide.

For consistency, the body should contain an array of users:

    Id: 1,
    FirstName: 'John',
    LastName: 'Doe'
    Id: 2,
    FirstName: 'Albert',
    LastName: 'Einstein'
  • I think this is a good example of API design. It probably isn't something I would allow in a public API as updating that many resources at once could be dangerous, but thanks for the example. – Joshua Dale Dec 17 '18 at 17:16

Your Answer

