Appropriate way to include additional top-level links?

1

Hello, we are evaluating whether JSON:API is a good fit as a specification to use to help provide a more cohesive API collection across a range of existing and new APIs we are building.

We have a need to include top-level links for a collection resource. In this case, it’s to provide a link to let the client know where to go to request elevated permissions so they can get additional access to content that’s been redacted from the current collection they are seeing.

We’d initially misinterpreted the spec assuming that “MAY include” meant that additional top-level links were allowed outside of “self” and pagination links. However, we’ve now realised that we should have interpreted “MAY include” to mean “MAY only include” and that this oversight might affect the ability for client libraries to work with our APIs :frowning:

What advice or suggestions are floating around to deal with this need? I didn’t find anything obvious in discussion here thus far.

Thanks in advance!
David

2

David,

My understanding of the specification has always been your first interpretation in that the links object for either document or resources may contain non-standard rels - I didn’t interpret the specification to be restrictive like your second interpretation. For example, here at movietickets.com our JSON API compliant REST API we do use some non-standard links in resources, it just means we had to document for clients what the non-standard links are for, etc.

If your second interpretation is confirmed by the specification owners, then you could always use the Meta object at the document level (or resource level?) to inform the client of your proprietary redacted content restrictions and how to get elevated permissions.

3

Confirmed here

And yes, since collections are not resources in JSON API, meta seems like the best way to go here.