Do You Know That Hypermedia Is A Better Solution For Discovery Than APIs.json?

I spend a lot of time field questions from people about APIs.json. This is something I expect to be doing for the next 10 years, and happy to field questions about exactly what it is all about, and help educate folks about exactly where APIs.json it fits in to the overall API landscape.

A regular comment I get from technologists, and API savvy folks is “you know that hypermedia is a better solution for discovery than APIs.json?” To which I reply “yes I know, but hypermedia is a solution for the API world we want, and APIs.json is a solution for the world we have”. I would love it if everyone understood hypermedia, and designed and deployed their APIs with this knowledge in mind—something I’ve spending a lot more time on in 2014, and will continue the push in 2015.

In the mean time, I intend to continue stitching apitogether thousands of APIs available out there, using APIs.json, allowing them to be discovered via open source public search engines like, private internal search engines, and IDE solutions like Codenvy. We don’t just need discovery solutions to find new APIs, we need ways to build collections of high value APIs, something APIs.json excels at.

Another thing that APIs.json does, that I don’t feel that hypermedia provides a solution to, is the discovery of the other technical, business, and political building blocks like the documentation, code libraries, SDKs, terms of service, and other critical elements of API operations. This an area that APIs.json was specifically defined for, allowing the discovery of these vital areas, in addition to the actual API interfaces.

As I do with many of my posts, this one is crafted to be a cookie cutter response to these comments I get regularly about hypermedia vs. APIs.json, allowing me to just reply with a link to this story on my blog. Hopefully we can shift the tide of API deployments in favor of hypermedia, but the APIs we can’t do this with, APIs.json is a healthy alternative, and I even recommend using it alongside hypermedia to provide easy access to the other critical building blocks of API operations, that technologists often overlook.