The Future of APIs.json (2020 Edition)

06 Sep 2020

This website and the conversation around APIs.json has been dormant for a couple of years. This was due to acquisitions, job changes, and just not enough time to invest in the specification beyond just putting it to use. Even though we haven’t iterated upon the version in a couple years doesn’t mean it has been put to the test when it comes to indexing internal and external APIs. With all this work, and a renewed energy in APIs, 2020 it feels like just the right time to get back to investing in the spec, and make recommendations for what the future of the APIs.json should look like.

API discovery still hasn’t been fixed as part of the overall API lifecycle, and more companies are just resorting to trying to make sense of the chaos after the fact, by indexing OpenAPI, log files, and other artifacts from across the API lifecycle, but alongside this madness there is also renewed interest in having a machine readable index of not just the OpenAPI and Swagger artifacts laying around, but also the other critical parts of API operations. Even with the growth in the adoption of Swagger and OpenAPI, these APIs specifications do not address the need for developers to find pricing, plans, rate limits, terms of service, documentation, SDKs, and the other building blocks of API operations. Resulting in a steady stream of questions from the community about what is APIs.json, and whether it might help us make sense of what is going on.

In 2020 we have refreshed the website for APIs.json, and [working on a proposal for version 0.16 of the specification](http://apisjson.org/format/apisjson_0.16.txt). This version includes some additional details for properties including name and media type, as well as opening up the conversation for a YAML edition of the spec. I have been pushing the specification in recent years to act as not just an index for individual APIs, but also for catalogs of APIs, and for blueprints that help you deploy templated APIs. As I push forward these conversations I am finding that having my APIs define as yaml is pretty critical to make the conversation more inclusive to business stakeholders, leaving conversations around the APIs.json nme pretty humorous. Opening up the doors for both JSON and YAML editions of the API discovery format, both leaning on the core specification to define what is possible with actual implementations.

Refreshing the website, updating the blog and Twitter account were the first business items on the list. Next we want to continue the conversation around the next version of the specification, getting us closer to an official 1.0 version that the community has helped define. There is still a lot of work to be done on the tooling side of things. There are a handful of open source tooling developed around the specification, as well as a growing number of API providers who have adopted the specification, but there is still a ton of work ahead to help make the specification something that is seen as the defacto API discovery format. We’ll continue going through the specification, as well as working on the available search engine, catalog, and toolbox implementations that put the specification to work. If you are using the APIs.json specification, or have comments and feedback about what the roadmap should look like, [please head over to GitHub issues for the project and share your thoughts](https://github.com/apis-json/api-json/issues). We look forward to hearing from you about what the future of APIs.json, and now APIs.yaml format might look like.