CODEWITHSUNDEEP
json-api
teaforthecat
teaforthecat

Reputation: 5093

can any named link go into the JSON:API "links" object or do we only get "self" and "related"?

I'm looking for examples or guidance on building a discoverable API, which would contain links to resources in the response body of the index path("/"). The JSON:API docs say "MAY" contain "self" and "related" links. related docs:

The value of each links member MUST be an object (a “links object”)

But it doesn't explicitly say the key of each link member can be anything, and it doesn't explicitly say that only "self" and "related" members are allowed. However, I'm not seeing any examples of link members named anything else.(?)

Is this a valid JSON:API response?

{"links": 
  "self": "/",
  "widgets": "/api/widgets"
}

Upvotes: 0

Views: 387

Answers (1)

jelhan
jelhan

Reputation: 6338

Links could have different context in JSON:API specification depending on where they occur in the JSON:API document. This is more clearly expressed in upcoming v1.1 of the specification:

A link’s context is the top-level object, resource object, or relationship object in which it appears.

https://jsonapi.org/format/1.1/#document-links

I assume that you are asking about allowed members for top-level links. Top-level links are the links for the JSON:API document.

The allowed top-level links are limited by the specification:

The top-level links object MAY contain the following members:

  • self: the link that generated the current response document.
  • related: a related resource link when the primary data represents a resource relationship.
  • pagination links for the primary data.

https://jsonapi.org/format/#document-top-level

Upcoming v1.1 introduces a describedby top-level link:

describedby: a link to a description document (e.g. OpenAPI or JSON Schema) for the current document.

Additional members could be specified by an extension in the upcoming v1.1. An extension can "extend the base specification by defining additional specification semantics." This includes defining additional members for objects:

An extension MAY define new members within the document structure defined by this specification.

Members defined by a specification must be namespaced:

When an extension defines new [...] document members, the extension MUST define a namespace to guarantee that extensions will never conflict with current or future versions of this specification.

Such a namespace is a string. It is applied to all members defined by the specification as a prefix using a colon : as separator.

By using an extension, you can add any members to the links object.

Upvotes: 1

Related Questions