Suppose I have an endpoint /api/todos and I make a PATCH request to change one of the todos. Does it ever make sense for my PATCH request to have in the response body the list of all of the todos?
Is there any specification that I can read about this?
I have talked to some developers and the general consensus is that the PATCH method should only return the changed entry. I agree with this point but am looking for documentation detailing this.
The RFC is here.
But it doesn't really specify anything. Here's an example from it:
Successful PATCH response to existing text file:
HTTP/1.1 204 No Content
Content-Location: /file.txt
ETag: "e0023aa4f"
The 204 response code is used because the response does not carry a
message body (which a response with the 200 code would have). Note
that other success codes could be used as well.
So you can implement it however you wish. Responding with just the changed entry would be more inline with how other methods (PUT, DELETE, etc.) are usually handled, so I would do it that way.
So when you want to provide a RESTfull api /api/todos represents a ressource where every todo has an separate id. Here you would patch e.g. to `/api/todos/4' to update the todo with the id 4.
The usual behaviour here would be to responde with either a 204 Status Code or with the updated object to save another request to get the updated todo.
If your todo's aren't separate objects with id's they are propably a list of items and should be returned all at once.
I like to use the Google API AIPs for most of my api development.
Small excerpt from AIP 134 which is about updates and PATCH.