Root path / opening comment

[jamesplease]

From the opening comments:

For example, it assumes that the client has a priori knowledge of types that exist on the server, since it does not define an entry point.

This is incorrect, I think. From @steveklabnik, one of the authors of JSON API:

The root path looks like any other JSON API response, we don't need a special one.

(Source: https://github.com/json-api/json-api/issues/126#issuecomment-37676482 )

This leaves a bit open for interpretation, but the gist is that you can just return some top-level links, and any other information that you would like. Here's one simple root endpoint that I've generated (this is returned as the root of /v1. For the root before that, you may link to the different hosted versions rather than to the resources, or if there's only one version available, you may just redirect to the root of that):

{
  "jsonapi": {
    "version": "1.0",
    "meta": {
      "extensions": []
    }
  },
  "meta": {
    "api_version": "1"
  },
  "links": {
    "cats": {
      "href": "/v1/cats",
      "meta": {
        "supported_actions": [
          "create",
          "read_one",
          "read_many",
          "update",
          "delete"
        ]
      }
    },
    "categories": {
      "href": "/v1/categories",
      "meta": {
        "supported_actions": [
          "create",
          "read_one",
          "read_many",
          "update",
          "delete"
        ]
      }
    },
    "people": {
      "href": "/v1/people",
      "meta": {
        "supported_actions": [
          "create",
          "read_one",
          "read_many",
          "update",
          "delete"
        ]
      }
    }
  }
}

The comment makes the point that you need a priori knowledge of the resources, but one of my favorite features of JSON API is its commitment to hypermedia. You should only need a priori knowledge of the root path of the API + the JSON API specification itself to use it. From there, the rest is given to you (you can imagine adding more meta for each resource that informs you of the relationships the resource has, the attributes it has, and so on, to enable you to use the different features of JSON API, like includes, fields, etc.).

Update: I just spun up an instance of this, and I see that the root endpoint is returned, but it's not a valid JSON API response. Would you be open to a PR that fixes that?

---

Another line in the opening comment is:

From a web architecture standpoint, it assumes tight coupling with the API consumer and the HTTP protocol.

This is true, for now, and it's especially easy for one to come away with this conclusion, given that the documentation is heavily centered around transporting the data over HTTP. But JSON API is being developed with the goal of one day being protocol agnostic. This is one reason why it is recommended that error codes be returned in the error object. I can find the source on that in the issues if you're interested, too!

--

Last, this opening comment communicates a lot of opinions about JSON API, which is a really good topic for a blog post, but I'm not sure if it's fitting for this library. For instance:

and relationship entities which are an entirely unnecessary complication.

You may be correct here. But is this the right place to make that argument? Do what you think is best, o' course, but I think it'd be more helpful if the comments here explained the code, rather than your opinions on JSON API.

In any event, I am pretty interested to hear more on your thoughts of JSON API. I get the sense that it isn't positive, but I'd love to hear more if you do have a blog 😛

[gr0uch]

Hypermedia in JSON API is optional, the spec doesn't mandate links. Even if it did make links mandatory, it's still up to the client to discover resources and that requires people to change their way of thinking, which is really hard to do. I completely made up the root endpoint myself because I thought it was missing, I wasn't even aware it's part of the spec. If it's not compliant then it should definitely be fixed.

I think my opinions matter, this is my project so it's like my little soapbox. JSON API is the first spec that approached web APIs holistically and considered practical concerns for real world apps. But they got a lot of things wrong in the design in my opinion and it's impossible to backtrack now. I think the future will be something like Hydra (JSON-LD vocab), or even my own µ API spec (JSON-LD based, it's still a draft though).

I recently started blogging again but I don't write about programming topics. Perhaps I should.