This is part four, sub-series 3, of the API design best practices series. Jump to sub-series 1 of the hypermedia sub-series.
- Read part one: Plan Your API »
- Read part two: Spec Driven Development »
- Read part three: Nouns, CRUD, and more »
A Road Trip
First off, let me apologize for the delay in this third part of the hypermedia sub-series. Christmas meant a warm trip back to Minnesota, a road trip through the Texas panhandle, and numerous snow storms in between — until finally I had the chance to cut through the mountainous desert of Southern California on my way back to beautiful San Francisco.
Now I understand some of you are probably wondering what any of that has to do with this post, other than it’s about 3 weeks after promised. One of the greatest challenges of the drive was battling my way through the snow and construction, and just hoping that the interstate would stay open (they literally close the interstates if it’s bad enough). But the one thing I could be sure of was that at every turn, between my steady GPS and road signs, I knew where I was going, and I knew when my path was being detoured or I couldn’t take a certain road… I knew this, because everything was nice and uniform.
In a lot of ways, APIs are like roads — they are designed to help us transport data from one point to another. But unfortunately, unlike the DOT system that spans the country, the directions (hypermedia) aren’t always uniform, and depending on the API we use, we’ll probably have to utilize a different hypermedia spec — one that may or may not provide the same information as others.
What essentially every hypertext linking spec does provide is a name for the link and a hypertext reference, but outside of that, it’s a crapshoot. As such, it’s important to understand the different specs that are out there, which ones are leading the industry, and which ones meet your needs. We may not be able to get it down to one spec, but at least we’ll be able to provide our users with a uniform response that they can easily incorporate into their application:
Collection+JSON
Collection+JSON is a JSON-based read/write hypermedia-type designed by Mike Amundsen back in 2011 to support the management and querying of simple collections. It’s based on the Atom Publication and Syndication specs, defining both in a single spec and supporting simple queries through the use of templates. While originally widely used among APIs, Collection+JSON has struggled to maintain its popularity against JSON API and HAL.
Strengths: strong choice for collections, templated queries, early wide adoption, recognized as a standard Weaknesses: JSON only, lack of identifier for documentation, more complex/ difficult to implement
JSON API
JSON API is a newer spec created in 2013 by Steve Klabnik and Yahuda Klaz. It was designed to ensure separation between clients and servers (an important aspect of REST) while also minimizing the number of requests without compromising readability, flexibility, or discovery. JSON API has quickly become a favorite receiving wide adoption and is arguably one of the leading specs for JSON based RESTful APIs. JSON API currently bares a warning that it is a work in progress, and while widely adopted not necessarily stable.
Strengths: simple versatile format, easy to read/ implement, flat link grouping, URL templating, wide adoption, strong community, recognized as a hypermedia standard
Weaknesses: JSON only, lack of identifier for documentation, still a work in progress
HAL
HAL is an older spec, created in 2011 by Mike Kelly to be easily consumed across multiple formats including XML and JSON. One of the key strengths of HAL is that it is nestable, meaning that _links can be incorporated within each item of a collection. HAL also incorporates CURIEs, a feature that makes it unique in that it allows for inclusion of documentation links in the response – albeit they are tightly coupled to the link name. HAL is one of the most supported and most widely used hypermedia specs out there today, and is surrounded by a strong and vocal community.
Strengths: dynamic, nestable, easy to read/ implement, multi-format, URL templating, inclusion of documentation, wide adoption, strong community, recognized as a standard hypermedia spec, RFC proposed Weaknesses: JSON/XML formats architecturally different, CURIEs are tightly coupled
JSON-LD
JSON-LD is a lightweight spec focused on machine to machine readable data. Beyond just RESTful APIs, JSON-LD was also designed to be utilized within non-structured or NoSQL databases such as MongoDB or CouchDB. Developed by the W3C JSON-LD Community group, and formally recommended by W3C as a JSON data linking spec in early 2014, the spec has struggled to keep pace with JSON API and HAL. However, it has built a strong community around it with a fairly active mailing list, weekly meetings, and an active IRC channel.
Strengths: strong format for data linking, can be used across multiple data formats (Web API & Databases), strong community, large working group, recognized by W3C as a standard
Weaknesses: JSON only, more complex to integrate/ interpret, no identifier for documentation
Siren
Created in 2012 by Kevin Swiber, Siren is a more descriptive spec made up of classes, entities, actions, and links. It was designed specifically for Web API clients in order to communicate entity information, actions for executing state transitions, and client navigation/ discoverability within the API. Siren was also designed to allow for sub-entities or nesting, as well as multiple formats including XML – although no example or documentation regarding XML usage is provided. Despite being well intentioned and versatile, Siren has struggled to gain the same level of attention as JSON API and HAL. Siren is still listed as a work in progress.
Strengths: provides a more verbose spec, query templating, incorporates actions, multi-format
Weaknesses: poor adoption, lacks documentation, work in progress
Other Specs
Along with some of the leading specs mentioned above, new specs are being created every day including UBER, Mason, Yahapi, and CPHL. This presents a very interesting question, and that is are we reinventing the wheel, or is there something missing in the above specs. I believe the answer is a combination of both, with developers being notorious for reinventing the wheel, but also because each developer looks at the strengths and weaknesses of other specs and envisions a better way of doing things.
You may recognize this issue from the last post, where some specs were modified by the companies using them to meet their individual needs. For example, PayPal wanted to include methods in their response, but you’ll notice that only Siren of the above include methods in the link definition.
The Future of Specs
Given that new specs are being created every day, each with different ideas and in different formats, it’s extremely important to keep your system as decoupled and versatile as possible, and it will be very interesting to see what the future of hypermedia specs will look like.
In the mean-time, it’s best to choose the spec that meets your needs, while also being recognized as a standard for easy integration by developers. Of the specs above, I would personally recommend sticking with HAL or JSON API, although each has its own strengths and weaknesses, and I believe that universal spec of the future has yet to be created. But by adhering to these common specs while the new specs battle things out, I think we will finally find that standard method of road signs, detours, and a single solution to provide API clients with a standardized GPS system.
For more on the different specs, I highly recommend reading Kevin Sookocheff’s review. I’d also love to hear your thoughts in the comments below.
And if you have your own pictures of @MaxtheMule, be sure to join our Champions Program and share them to earn points towards cool rewards such as iPads, 3D Printers, MuleSoft training and swag, drones, USB-powered fridges, and so much more!
Go to Part 5: Response Handling →
- Using HTTP Status Codes
- Returning Descriptive Error Messages
