Make the spec explicit about URL structure

1

The FAQ states that a server is free to choose any URL structure. However, looking at the existing implementations, I see that some of them assume a fixed structure like host:port/type/id or base_url/type/id, and don’t provide an obvious way of querying arbitrary resources located at custom URLs. As well, some discussions on the forum show that this aspect is not obvious to people.

In order to avoid losing this important feature of JSON API, I suggest that the spec be made more explicit about it.

For example, the spec could incorporate the following text (not sure where, perhaps closer to where type and id are defined):

JSON API is designed to be agnostic of the URL structure used by the server. As far as is practical, clients SHOULD use the links provided by the server, rather than construct the URLs on their own. Client libraries SHOULD make it possible to interact with arbitrary resources at custom URLs. Clients SHOULD also be prepared to handle HTTP redirections, including 307 Temporary Redirect and 308 Permanent Redirect.

A more subtle approach is to rewrite all examples in the spec with a variety of URL structures, so that the reader can’t infer a single pattern and assume that it’s the rule.

1 Like
2

Maybe something like an accompanying Best Practices document alongside can help. With some of the intentions that led to certain aspect of the JSON API explained. Also what a client can expect from the API and how to brachiate through the API (which both helps client and server devs).

3

There is some info in JSON:API — Recommendations which I can’t tell if you’ve looked at.

URL Design

Reference Document

When determining an API’s URL structure, it is helpful to consider that all of its resources exist in a single “reference document” in which each resource is addressable at a unique path. Resources are grouped by type at the top level of this document. Individual resources are keyed by ID within these typed collections. Attributes and links within individual resources are uniquely addressable according to the resource object structure described above.

This concept of a reference document is used to determine appropriate URLs for resources as well as their relationships. It is important to understand that this reference document differs slightly in structure from documents used to transport resources due to different goals and constraints. For instance, collections in the reference document are represented as sets because members must be addressable by ID, while collections are represented as arrays in transport documents because order is significant.

URLs for Resource Collections

It is recommended that the URL for a collection of resources be formed from the resource type.

For example, a collection of resources of type photos will have the URL:

/photos
URLs for Individual Resources

Treat collections of resources as sets keyed by resource ID. The URL for an individual resource can be formed by appending the resource’s ID to the collection URL.

For example, a photo with an ID of “1” will have the URL:

/photos/1
Relationship URLs and Related Resource URLs

As described in the base specification, there are two URLs that can be exposed for each relationship:

the “relationship URL” - a URL for the relationship itself, which is identified with the self key in a relationship’s links object. This URL allows the client to directly manipulate the relationship. For example, it would allow a client to remove an author from a post without deleting the people resource itself.

the “related resource URL” - a URL for the related resource(s), which is identified with the related key within a relationship’s links object. When fetched, it returns the related resource object(s) as the response’s primary data.

It is recommended that a relationship URL be formed by appending /relationships/ and the name of the relationship to the resource’s URL.

For example, a photo’s comments relationship will have the URL:

/photos/1/relationships/comments
And a photo’s photographer relationship will have the URL:

/photos/1/relationships/photographer
It is recommended that a related resource URL be formed by appending the name of the relationship to the resource’s URL.

For example, the URL for a photo’s comments will be:

/photos/1/comments
And the URL for a photo’s photographer will be:

/photos/1/photographer
Because these URLs represent resources in relationships, they should not be used as self links for the resources themselves. Instead the recommendations for individual resource URLs should still apply when forming self links.