It's relatively easy to understand when you get your head around it. Until then, it's not obvious at all I found.
There are three types of URLs in JSON-API.
- Resource URLs. This is - for example - "/articles/1"
- Related Resource URLs. This is - for example - "/articles/1/author"
- Relationship URLs. This is - for example - "/articles/1/relationships/author"
The "Resource URL" is a direct URL to a resource, or collection of resources.
The "Related Resource URL" is a stable URL to a resource related to another one. This confused me a lot to start with. As an example here, if the current author of Article 1 is Person 3 then "/articles/1/author" will return the same as "/people/3". If the current author of Article 1 were to somehow be changed to Person 5 then "/articles/1/author" will still return the current author of Article 1, but this will now be the same as "/people/5" instead.
This means that you can always rely on "/articles/1/author" to return the current author of Article 1, whichever resource that is. It's a case of having stable URLs that point to different data, instead of the URL itself changing when the data changes.
The "Relationship URL" is going to return information about the Relationship between two resources, instead of the Related Resource itself. Unfortunately the fact that a Relationship can not have any data of it's own limits the usefulness of this, but it still has some benefit.
As a worked example:
- GET /articles/1 - This will return Article #1
- GET /articles/1/author - This will return Person #3
- GET /articles/1/relationships/author - This will return the following:
Literally just the details of the relationship between Article #1 and it's Author - Person #3.
The real benefit of this is when you want to edit them. You can do a
PUT /articles/1/relationships/author with the details of the new author, or (Bad example here) a
DELETE /articles/1/relationships/author to delete the Relationship between the two. This does not delete the Person record, just the connection between the Article and the Person.