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

**URL:** <https://discuss.jsonapi.org/t/top-level-links-vs-resource-level-links-for-item-resources/2032>\
**Category:** Uncategorized\
**Created:** [August 20, 2020, 8:03am UTC](https://discuss.jsonapi.org/t/top-level-links-vs-resource-level-links-for-item-resources/2032 "2020-08-20T08:03:50Z")\
**Posts on this page:** 3\
**Page:** 1

<div class="post-metadata">

**Author:** ![toedter-k](https://sea2.discourse-cdn.com/flex016/user_avatar/discuss.jsonapi.org/toedter-k/32/695_2.png) [@toedter-k](https://discuss.jsonapi.org/u/toedter-k)\
**Post date:** [August 20, 2020, 8:03am UTC](https://discuss.jsonapi.org/t/top-level-links-vs-resource-level-links-for-item-resources/2032/1 "2020-08-20T08:03:51Z")

</div>

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](https://github.com/toedter/spring-hateoas-jsonapi))  
I am thinking about making the preferred style configurable.

What do you think?

---

<div class="post-metadata">

**Author:** ![jelhan](https://sea2.discourse-cdn.com/flex016/user_avatar/discuss.jsonapi.org/jelhan/32/822_2.png) [@jelhan](https://discuss.jsonapi.org/u/jelhan)\
**Post date:** [December 13, 2020, 3:04pm UTC](https://discuss.jsonapi.org/t/top-level-links-vs-resource-level-links-for-item-resources/2032/2 "2020-12-13T15:04:57Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![prathe](https://sea2.discourse-cdn.com/flex016/user_avatar/discuss.jsonapi.org/prathe/32/643_2.png) [@prathe](https://discuss.jsonapi.org/u/prathe)\
**Post date:** [July 6, 2022, 12:03pm UTC](https://discuss.jsonapi.org/t/top-level-links-vs-resource-level-links-for-item-resources/2032/3 "2022-07-06T12:03:51Z")

</div>

> [@jelhan](#):
>
> 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.

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.