Should the PATCH method return all fields of the resource in the response body?

Nigiri picture Nigiri · Jun 9, 2016 · Viewed 23.1k times · Source

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
}

Answer

Robert Bräutigam picture Robert Bräutigam · Jun 9, 2016

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.