As a co-author of JSON API, I'd like to address the value proposition of the specification.
First of all, JSON API provides guidance for a lot of API design decisions that are usually contentious because, although they may seem trivial, they must be made with care in order to be consistent and viable. For instance, JSON API provides guidance for:
* fetching related resources together with primary resources in order to minimize requests
* limiting the fields included in a response document in order to minimize payload size
* paginating data with links that work well with any pagination strategy (page-based, offset-based, and cursor-based)
* sorting results, even potentially based on related resource fields
* representing heterogeneous collections and polymorphic relationships
* representing errors
In my opinion, some of the most useful guidance is related to the representation of relationships, which can include:
* embedded linkage data which "links" primary resources with related resources in a compound document.
* relationship URLs which can retrieve linkage data and directly manipulate the relationship without affecting the underlying resources.
* related resource URLs which can retrieve related resources themselves.
In addition, JSON API supports extensions and has official extensions for performing bulk updates and JSON Patch operations. These particular extensions provide extremely useful mechanisms for transactionally working with multiple resources.
All of this guidance has been forged over the course of two years based on the feedback and contributions of hundreds of developers. Even if you were to incorporate some of this guidance in your APIs piecemeal, it would probably save your team many hours of design discussions.
However, 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.
We are seeing client libraries being built in JavaScript, iOS, and Ruby, and server libraries in PHP, Node.js, Ruby, Python, Go, and .NET. Although not all are (yet) compliant with the latest changes to the spec, we are tracking progress carefully as the spec nears 1.0 to ensure that we smooth over any rough spots encountered by implementors. I'm personally involved in developing Orbit.js and JSONAPI::Resources, both of which are nearing JSON API compliance.
I can say that it's incredibly satisfying to build applications with compatible client and server libraries. It lets me focus on the design of my application's domain instead of myriad details related to transforming data representations and protocol usage. Even better is the knowledge that other clients can easily use my API and all of its advanced features, regardless of their language and framework. This is ultimately the promise of JSON API, and it won't be long before it's realized.
Five years ago, much of my team's time was being consumed fighting with the WSDL and SOAP specs, and their various subtly incompatible or outright broken implementations on our target platforms.
A switch to JSON-RPC 2.0 meant everyone now understood the entirety of the specifications our APIs relied on, and if we couldn't find a good implementation for our target, we could either fix one, or write one ourselves in just a few hours.
The productivity gain was effectively infinite.
I look at the JSON API specification in all its architecture astronaut glory, and weep.
First of all, JSON API provides guidance for a lot of API design decisions that are usually contentious because, although they may seem trivial, they must be made with care in order to be consistent and viable. For instance, JSON API provides guidance for:
* fetching related resources together with primary resources in order to minimize requests
* limiting the fields included in a response document in order to minimize payload size
* paginating data with links that work well with any pagination strategy (page-based, offset-based, and cursor-based)
* sorting results, even potentially based on related resource fields
* representing heterogeneous collections and polymorphic relationships
* representing errors
In my opinion, some of the most useful guidance is related to the representation of relationships, which can include:
* embedded linkage data which "links" primary resources with related resources in a compound document.
* relationship URLs which can retrieve linkage data and directly manipulate the relationship without affecting the underlying resources.
* related resource URLs which can retrieve related resources themselves.
In addition, JSON API supports extensions and has official extensions for performing bulk updates and JSON Patch operations. These particular extensions provide extremely useful mechanisms for transactionally working with multiple resources.
All of this guidance has been forged over the course of two years based on the feedback and contributions of hundreds of developers. Even if you were to incorporate some of this guidance in your APIs piecemeal, it would probably save your team many hours of design discussions.
However, 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.
We are seeing client libraries being built in JavaScript, iOS, and Ruby, and server libraries in PHP, Node.js, Ruby, Python, Go, and .NET. Although not all are (yet) compliant with the latest changes to the spec, we are tracking progress carefully as the spec nears 1.0 to ensure that we smooth over any rough spots encountered by implementors. I'm personally involved in developing Orbit.js and JSONAPI::Resources, both of which are nearing JSON API compliance.
I can say that it's incredibly satisfying to build applications with compatible client and server libraries. It lets me focus on the design of my application's domain instead of myriad details related to transforming data representations and protocol usage. Even better is the knowledge that other clients can easily use my API and all of its advanced features, regardless of their language and framework. This is ultimately the promise of JSON API, and it won't be long before it's realized.