Help interpreting "7.3.1 Updating To-One Relationships"


I am trying to make my API follow the JSON:API spec very strictly, but I’m a little confused on sections 7.3.1 and 7.3.2.

A server MUST respond to PATCH , POST , and DELETE requests to a URL from a to-many relationship link as described below.

If a client makes a PATCH request to a URL from a to-many relationship link, the server MUST either completely replace every member of the relationship, return an appropriate error response if some resources can not be found or accessed, or return a 403 Forbidden response if complete replacement is not allowed by the server.

Does this mean that I cannot have “read-only” relationship routes?

For example if I only want to have this route for the “comments” relationship:
GET /api/posts/{id}/relationships/comments

My server would fail rule 7.3.2 because it does NOT respond to POST, PATCH, or DELETE requests as the rule describes. It would respond with a 404.
Do I need to have the routes available, and return 403 Forbidden instead?


You are in the section about “updating relationships”. There is another one about “fetching relationships” where you find the info you need. Also, you are reading these MUST statements out of context, have a look at the beginning of section 7:

A server MAY allow resources of a given type to be created. It MAY also allow existing resources to be modified or deleted.

1 Like

Welcome to the community, @BillTracy!

OT, but I want to say thanks for using the new section citations! Hopefully, the numbering proved useful for you in both the use of the specification and asking your question!

1 Like

@claudenirmf Thank you for pointing that out. That totally clears things up. I must’ve missed that section.

@timothy.stone Thanks for the kind words and I agree the section numbering helped greatly as well as putting the “musts & mays” in bold. Describing the spec so concisely is certainly an impressive feat.

Thanks again

1 Like