Structure of "reference document"

1

Hi, I’m new to the forum and relatively new to JSON:API and I’m struggling to understand what the root URI of an API should return. I couldn’t find an answer using search.

The page JSON:API — Recommendations (jsonapi.org) mentions a top-level reference document and states:

Resources are grouped by type at the top level of this document. Individual resources are keyed by ID within these typed collections.

I don’t understand what it means that »resources are keyed by ID« – do these collections use a data object instead of a data array as elsewhere in the spec?

The next paragraph goes on to say

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.

Here, I don’t understand how these »sets« should be physically represented in the protocol? There is no example what such a »reference document« should look like. It sounds like it should be a »collection of typed collections«, so the API root could perhaps return something like this:

{
  "data": [{
    "type": "collections",
    "id": "articles",
    "links": {
      "self": "http://example.com/articles"
    }
  }, {
    "type": "collections",
    "id": "comments",
    "links": {
      "self": "http://example.com/comments"
    }
  }],
  "links": {
    "self": "http://example.com"
  }
}

But making up a type for this kind of resource seems arbitrary.

Another way would be to represent the root document as having relations to all the »typed collections«:

{
  "data": {
    "type": "root",
    "id": "root",
    "relationships": {
      "articles": {
        "links": {
          "related": "http://example.com/articles"
        }
      },
      "comments": {
        "links": {
          "related": "http://example.com/comments"
        }
      }
    }
  },
  "links": {
    "self": "http://example.com"
  }
}

But in this case I can’t work out what the "self" link of those relationship objects should be?

And even then, I still don’t understand how resources should be »keyed by ID« in those typed collections?

Alternatively, the root URI could forward to the API’s »main collection«, http://example.com/articles in this example.

I would really appreciate any advice on what others are returning from their API’s root URI to provide an »entrance point« for the clients.

2

The specification itself is agnostic about the URL schema. You can use any format you like.

The recommendation is using resource type as URL for endpoints representing a collection of resources of that type. E.g. the endpoint representing a collection of posts would be /posts.

An individual resource would use a sub-path on that collection including the ID: /photos/{id} E.g. the resource { type: "photos", id: "4" } would habe the URL /photos/4.

That’s all the recommendation is trying to say per my understanding.

3

Hi @jelhan, thanks a lot for your reply.

My question wasn’t so much about the URL schema but about the actual content of the »reference document« – I think of that as basically the »landing page« of the API which is served from the root / URL.

I believe the page I quoted is trying to describe what that should look like, but I don’t really understand what it’s suggesting and would greatly appreciate an example of how others are designing their API’s »landing document«.

4

That recommendation is not about a root to enter a graph or related resources. Typically a REST API implementing HATEOAS has many potential entry points. E.g. for a blog entry points could be the posts, the authors, or tags. I would recommend documenting the supported entry points.

The main difference between documented entry points and other URLs of your API is only the stability guarantees you are providing for the URLs. URLs only discoverable over linkage within a JSON:API document may change at any time. While changing those URLs documented as entry points would be a breaking change. And covered by change management processes.