restputhttp-puthttp-patch

Response body when PATCHing a collection


In my REST API I have a very large collection; it contains millions of items. The path for this collection is /mycollection

Because this collection is so large it is not good practice to GET the whole collection so the API supports paging. Paging will be the primary way of getting the collection

GET /mycollection?page=1&page-size=100 HTTP/1.1

Say the original collection contains 1,000,000 items and I want to update 5,000, delete 3,000 and add 2,000 items. I could write my API to support updating the collection via either the PUT method or the PATCH method. While either method would require very different request bodies I believe both methods would require the exact same response body, i.e. the response body would have to contain the current representation of the entire updated resource, i.e. all 999,000 items in the collection.

As I mentioned earlier GETting the entire collection is just not realistic; it's too big. For the same reason I don't want PUTting or PATCHing to return the entire collection. Adding query parameters to a PUT or PATCH request wouldn't work either because neither PUT nor PATCH are safe methods.

So what would be the proper response in this large collection scenario?

I could respond with

HTTP/1.1 202 Accepted
Location: /mycollection?page=1&page-size=100

The 202 Accepted response code doesn't feel correct because the update would have been done synchronously. The Location header doesn't quite feel right either. I could maybe go with a Links header, but still it doesn't feel right.

Again I ask what would be the proper response in this large collection scenario?


Solution

  • This question is based on a misconception:

    While either method would require very different request bodies I believe both methods would require the exact same response body, i.e. the response body would have to contain the current representation of the entire updated resource

    Either can just return 204 No Content or 200 OK and no response body. There's no requirement that they include the full representation in the response.

    You could optionally support this (perhaps along with the Prefer: return=representation header, or perhaps Content-Location header), but without this header I would say it's not even a convention that the current representation is returned. Generic clients shouldn't assume that the response body is the new representation unless these headers are used.

    So, just return a 2xx and you're good to go.