JSON API Spec Goes Through The Hacker News Gauntlet

JSON API is based on the JSON transport defined by the REST adapter in the Ember Data Library used by the Ember.js JavaScript Framework. Its editors include well-known names in the JavaScript community, including Steve Klabnik and Yehuda Katz.

So how are developers responding to it? Not surprisingly, it has a fair share of both supporters and detractors. Here are selected comments (full and partial) from a Hacker News thread.


I definitely see some benefits with json- API. Here are two:

1. When writing large single-page apps in JS, client <-> backend communication will need some structure. Could be a few project-internal guidelines, or something like json-api.

2. Client frameworks and backend frameworks are often separate projects (e.g. Django/express/sinatra server-side or React/Backbone/Mithril client-side). It's helpful with a standard to converge on for authors of backend json/rest serializers, and data adapters client-side.


Anyone who sets out to write a hypermedia API in JSON is going to end up with a structure not dissimilar to this one. If this fits your needs, then use it, by all means and let your clients use an off-the-shelf lib for using your service.

I'm not a fan of the spec, but overall it seems to strike a good balance between what is specified and what is left out. To compare this to SOAP is missing the point. 


It's a valiant effort but as someone who has dealt with unraveling a strict API built with SOAP I am going to pass. If I want something standardized I will use a schema based solution such as Protobuf. It's already a quasi standard, has clients in many languages and is a binary protocol.

We also should not confuse an API with a transport protocol. I will tilt my hat to this not being as verbose as past attempts, but why reinvent the wheel yet again? It's not like prior attempts didn't Function as expected - they did - but we in the industry chastised them for being too strict.

Let's work on improving the semantics and Documentation around what constitutes an API. Swagger is an excellent example of this.


Wow. No one needs this. API means Application Programming Interface. It starts and ends its standardization at the application level.

Make your API consistent and write decent documentation for it. That's all anybody needs and will be simpler then trying to conform to some insane metastandard.


Please don't make JSON into JXML.

dgeb (co-author of JSON API specification):

...the bigger value proposition of JSON API is just now beginning to be realized. Since we've tightened the "spec" into a proper spec by eliminating many MAYs and SHOULDs, it is now possible to reliably build implementations with a guarantee of compatibility. It's regrettable that it took us so long to move from providing loose guidelines to a more rigid spec, but I truly believe that the awkward intermediate phase provided invaluable feedback that ultimately informed the design of the spec and will improve adoption of 1.0.


If I wanted a complicated standard but one with broad consensus and lots of library support behind it, why wouldn't I just use XML- RPC? Other than not being XML, what does JSON API offer? Because at first glance, it looks just about as verbose and unfriendly as XML-RPC to me.


We're starting to build API endpoints with this where I work. We didn't have compound documents in an earlier version of our API, and we ended up having to make a lot of roundtrips for some things. So I had been thinking about something like the jsonapi "include" mechanism, and when I saw how jsonapi was doing it, it was pretty close to what I would have done. That made me feel better about going along with their decisions in areas I haven't thought about.


In case you're thinking, "Wow, I bet in the real world this would be a misery to impose on a team - I'm sure no one would really want to do this!", well, I worked briefly with a team where they imposed this. It was part of the reason why I say "briefly".


It opens a path for standardized tooling among API clients. Rather than having a whole mess of JSON-over- HTTP clients with a hard-coded understanding of the particular API, one could theoretically use a hypertext client to interact with any API using this standard.

What do you think about the proposed JSON API standard? Is it something you would consider using? Let us know in the comments. 

Be sure to read the next API Design article: In a REST world, there’s room for non-REST APIs