King & McGaw Developers

I was interested to see jsonapi.org spring up on the web recently. Though it’s authored by Ember’s team, the references to Ember have been moved from the homepage to the history section, and it’s clear that the ambition is to set a standard for API compatibility between servers and clients.

Overall I applaud the ambition and it’s clearly written by clever people. That said, I believe consuming the proposed data structures is more complicated unless you’re using a compatible library.

Consider these examples…

If the value of a resource key is a JSON object, the value represents a single document. If the value of a resource key is a JSON array, the value represents a list of documents.

Isn’t it better to have the URL scheme define if you are looking at a document or collection? i.e. GET /resource is a collection and GET /resource/document is a document?

To save HTTP requests, it may be convenient to send related documents along with the requested documents.

For example:

{
  "posts": [{
    "id": "1",
    "title": "Rails is Omakase",
    "rels": {
      "author": 9
    }
  }],
  "people": [{
    "id": "9",
    "name": "@d2h"
  }]
}

So to list the post title and author name would be something like (pseudo code):

{posts.each (post)}
  {post.title} by {people.where(id: post.rels.author).name}
{end}  

Now, that’s pseudo-code, and in reality it would depend on what language or framework you are using as to how easy that “where” statement is. It’s definitely going to be a lot more complicated than my example to do it in vanilla JavaScript. I’d suggest that nesting the documents is much easier:

{
  "posts": [{
    "id": "1",
    "title": "Rails is Omakase",
    "author": {
      "id": "9",
      "name": "@d2h"
    }
  }]
}

And it can be consumed like this:

{posts.each (post)}
  {post.title} by {post.author.name}
{end}  

Yes, it’s imperfect and can result in more duplication and less flexibility, but I think for a lot of cases that isn’t an issue.