Support updating through relationship links required?


Hi! I have a question about this section of the spec:

"Although relationships can be modified along with resources (as described above), JSON API also supports updating of relationships independently at URLs from relationship links."

So, I understand that the relationships can be modified through PATCH requests to the resource itself (something like books/1), or by PATCH requests to relationship links (something like /books/1/relationships/author). But is the server also required to support relationship links/updates through relationship links, or is that optional?

Thanks in advance!


Are you asking if you have to support an update to author through /books/1/relationships/author? I am pretty sure this is not supposed to be possible. You do also no show individual authors with links like /books/1/relationships/author/uuid-of-author.

Is that what you are asking, or did I misunderstand you?


@lukasoppermann Thanks for responding! I think what you’re describing is not quite what I’m talking about–what I’m asking about is updating the relationship of, in this example, a book’s author, through a PATCH request to a relationship link. So you aren’t changing the author itself, you are just changing which author a book has. It’s described in this part of the spec:

The reason I’m wondering if this is required is because you could accomplish the same thing by just sending an update request to the author itself with the new relationship specified (this is described in the spec here: And the description in the spec here seemed a little ambiguous as to whether the server needed to support both of these strategies:


The way I read the spec, it’s the /relationships/ strategy that has to be supported, and the “via the resource” strategy is optional.


The spec is quite clear that you MUST support editing the relationship like this. Under the section “Updating Relationships > Updating To-One Relationships”

A server MUST respond to PATCH requests to a URL from a to-one relationship link as described below.

Further to that, under the section “Updating Resources > Updating a Resource’s Relationships”, the wording is instead:

Any or all of a resource’s relationships MAY be included in the resource object included in a PATCH request.

Meaning that you can choose to support this if you wish, but there’s no need to do so.

Edit: Actually, on re-reading that, it says the server must respond to the request. You can always choose to respond that the request is not allowed and still follow the letter of the spec, but I’d argue you’re then not following the spirit of the spec.


Thanks @Sazzer and @jlangley --that makes sense! The clarification that “respond” could technically mean responding that it’s not allowed yet was helpful.


That phrase could do with some clarification in a later version. Does it refer to the relationship link, to the URL, to the PATCH request, or to the server response?


@jlangley I think it’s meant to refer to the response from the server, which is described immediately below. I think all of the other options are actually described above that line in the document.


The PATCH request is described immediately below :innocent:.
But I agree - I think the phrase applies to the response, i.e. to this, which would allow the server to respond with a 403 as you suggest :slight_smile:


Ah - PATCH is described twice. Once under “Updating Relationships” which is immediately below as you say, but also under “Updating Resources” which is higher up. I’d somehow not noticed that…


@speterson14 - Reading over things in the Spec again, and there is another option that comes to mind. You don’t actually need to support the Relationship link at all.

When you have a Relationship, you must provide at least one of “self” and “related”. The “self” link is a link to the relationship record, as opposed to the record you are related to. The only real benefits of this are:

  • It allows you to edit the Relationship directly, instead of editing it via the resource.
  • It allows you to retrieve extra information about the relationship itself.

You are trying to avoid the first of those being possible. If you don’t have any need for the second of those, then just don’t return a “self” link for the relationship, and the problems go away.


I know I’m a bit late to the party, but I found the answer to this in this issue on the the JSON API GitHub repo.