Update an entire resource collection in a REST way

Question

I have a REST URI for a list of resources, something like:

http://foo.com/group/users

Each of these users has a sequence number and I want

Answer 1

Semantically speaking, the HTTP PATCH method is the right way to go. This is also described in the currently chosen answer.

PATCH /group/users

[
    { "id": "userId1", "sequence": "newSequenceNumber1" },
    { "id": "userId2", "sequence": "newSequenceNumber2" },
    ...
]

However, the second method described in the chosen answer is not restful, because you invented new verbs inside a POST request. This is SOAP, not REST.

Answer 2

You can use both PATCH and POST on the URIs. I'd use PATCH if I were you. It's the best solution for bulk updates.

Answer 3

After the raffian's comment on my initial response, I reworked my answer to be more RESTful...

• Use the method PATCH

This method is typically designed to update partially the state of a resource. In the case of a list resource, we could send a list with only the elements to update and the identifiers of elements in the list. The following request would be:

PATCH /group/users
[
    { "id": "userId1", "sequence": "newSequenceNumber1" },
    { "id": "userId2", "sequence": "newSequenceNumber2" },
    (...)
]

• Use the method POST on the list resource

This method is commonly used to add an element in the list managed by the resource. So if you want to leverage it for this action, we need to pass within the request an hint regarding the action to execute. We have the choice to add this either in a dedicated header or within the payload.

With the header approach, you will have something like that:

POST /group/users
X-Action: renumbering
[
    { "id": "userId1", "sequence": "newSequenceNumber1" },
    { "id": "userId2", "sequence": "newSequenceNumber2" },
    (...)
]

With the payload approach, you will have something like that:

POST /group/users
{
    "action": "renumbering",
    "list": {
        [
            { "id": "userId1", "sequence": "newSequenceNumber1" },
            { "id": "userId2", "sequence": "newSequenceNumber2" },
            (...)
        ]
    }
}

Hope it helps you, Thierry