Including Id in URI for PUT requests

The PUT method requests that the state of the target resource be created or replaced with the state defined by the representation enclosed in the request message payload.

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

RFC 72314.3.4 PUT

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.

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'
  }
]