33

Should the PATCH method return all fields of the resource in the response body?
Or should it return only updated fields?

I'm reading this

For example, if it returns only updated fields, the user could know which fields were updated in the server, while the user updated some fields.

**Users resource representations**
name: string
age: number
createdon: date
modifiedon: date


PATCH /users/{userId}
Request body
{
  name: 'changedname',
}


Response body Case1
{
  name: 'changedname',
  age: 20,
  createdon: 2016-01-01,
  modifiedon: 2016-06-09
}


Response body Case2
{
  name: 'changedname',
  modifiedon: 2016-06-09
}
Community
  • 1
  • 1
Nigiri
  • 3,469
  • 6
  • 29
  • 52

3 Answers3

27

Normally this should be handled through content negotiation. In other words, the client asks for a specific representation if it needs one. The request would look like this:

PATCH /user/123
Content-Type: application/merge-patch+json
Accept: application/vnd.company.user+json
...

In this case, the client expresses that it wants a full user representation as answer. Or it could do:

PATCH /user/123
Content-Type: application/merge-patch+json
Accept: application/vnd.company.object-fragment+json
...

to ask for a generic fragment representation of some object.

You don't have to implement both if you don't want to, in which case you just do your use-case and respond with 406 Not Acceptable to media-types you do not support for the moment.

Robert Bräutigam
  • 7,514
  • 1
  • 20
  • 38
  • 1
    I find this answer a bit suspect. A client that sends`Accept: vnd.company.user+json` should expect to receive a response with that same `Content-Type`. But that's not `application/json`, nor do I see anything in RFCs 2046 or 9110 to indicate why it should be treated as such. The `+json` suffix only seems to be a convention among IANA-registered types that _explicitely state_ they use JSON in their specifications. My concern is that users expecting HTTP libs to recognize such responses as JSON and parse them accordingly may be surprised to find that doesn't work. – broofa Jan 23 '23 at 13:11
11

The specification of PATCH doesn't mandate this.

If you want to control it you may want to look at https://greenbytes.de/tech/webdav/rfc7240.html#return for inspiration.

Julian Reschke
  • 40,156
  • 8
  • 95
  • 98
4

I don't think the REST specification (btw I think you need to be looking at RFC 6902 for this) enforces any strong rules around this (what you should be returning). I'd rather return the whole resource so that the client can use it any way it needs. Theoretically, the client itself knows what what's been patched (at least what the request was). Getting confirmation from the server might not be trivial (especially given that PATCH is mostly used for collections), or at least not worthwhile.

Community
  • 1
  • 1
Alexandru Marculescu
  • 5,569
  • 6
  • 34
  • 50
  • There is a definition in RFC 5789, section 2.1: https://tools.ietf.org/html/rfc5789#section-2.1 – Juha Untinen Sep 15 '17 at 10:30
  • Although curiously it speaks of a document, but nothing else. ``Successful PATCH response to existing text file: HTTP/1.1 204 No Content Content-Location: /file.txt ETag: "e0023aa4f"`` – Juha Untinen Sep 15 '17 at 10:31
  • However, it also says: ``Note that other success codes could be used as well.`` (besides 204) – Juha Untinen Sep 15 '17 at 10:37