Body of sucessful relationship update response

1

Documentation section Updating Relationships says:

The response document MUST include a representation of the updated relationship(s).

Resource Team can has many members of User type.

{
  data: {
    type: "Team",
    id: "team-1",
    relationships: {
      members: {
        data: [
          {
            type: "User",
            id: "user-1"
          }
        ]
      }
    }
  }
}

If we want to update members list we could make PATCH request on relationship.

PATCH /teams/team-1/relationships/members

{
  data: [
    {
      type: "User",
      id: "user-1"
    },
    {
      type: "User",
      id: "user-2"
    },
  ]
}

What response client should expect?

  1. Same as request:
{
  data: [
    {
      type: "User",
      id: "user-1"
    },
    {
      type: "User",
      id: "user-2"
    },
  ]
}
  1. Or parent model including updated relationship:
{
  data: {
    type: "Team",
    id: "team-1",
    relationships: {
      members: {
        data: [
          {
            type: "User",
            id: "user-1"
          },
          {
            type: "User",
            id: "user-2"
          }
        ]
      }
    }
  }
}
2

The first one. (i.e., the response should, I think, always be the same as what the client would get back by immediately making a GET to the same endpoint, assuming GET is supported.)

1 Like
3

Yeah. I’ve thought this way too. But after starting to implement relationship endpoints in real project I’ve understood that developers should require to implement additional mechanisms for updating relations in their local storages instead of simple resource data merge. I’m not talking against returning first solution, just explaining why I’ve started to doubt.

This solution will require additional serializer on backend, additional frontend resource relationship’s merge mechanisms, but as you correctly noted will bring consistency with GET requests and should reduce server load.

4

Server must return with a 204 No Content in your given example:

A server MUST return a 204 No Content status code if an update is successful and the representation of the resource in the request matches the result.

Server must only return a 200 OK in this two cases:

If a server accepts an update but also changes the targeted relationship(s) in other ways than those specified by the request, it MUST return a 200 OK response. The response document MUST include a representation of the updated relationship(s).

A server MUST return a 200 OK status code if an update is successful, the client’s current data remain up to date, and the server responds only with top-level meta data. In this case the server MUST NOT include a representation of the updated relationship(s).