Top-level links vs. resource-level links for item resources

In JSON:API, links for item-resources can either be put on top-level or on resource-level.

Is there a best practice to prefer the one or the other (or even both)?

I am the author of a JSON:API implementation for Spring HATEOAS
(https://github.com/toedter/spring-hateoas-jsonapi)
I am thinking about making the preferred style configurable.

What do you think?

The top-level self link may equal the self link of a resource. But not in all cases.

The top-level self link is specified as the “link that generated the current response document.” In most cases that’s the same link as used by the client to fetch the response document. It may include query parameters for sorting, filtering, sparse fieldset and inclusion of related resources.

The self link of a resource is specified as the “link that identifies the resource represented by the resource object.” This only equals the top-level self link if a single resource is fetched without using a sparse fieldset or including related resources.

For relationships the self link is specified as “a link for the relationship itself”. This is called a “relationship link” in the specification. It allows a client to fetch the resource linkage of a relationship. Additionally it “allows the client to directly manipulate the relationship.” It can be used to associate two existing resources with each other and to remove that associate later.

Only taking the self link into account it highlights that the links object has different meaning on all levels. I don’t think it’s a question of supporting either or. All of them provide value in specific use cases. I would recommend to let your users choose which once to include per request.

When fetching a related link from a to-one relationship, the top-level self link would be the related link that generated the document which would be different from the resource self link.

1 Like