The UK has an arcane phrase about how today’s newspapers are tomorrow’s fish and chip wrappers. That phrase no longer rings true in our world of digital media and online news outlets (and if you live in countries that don’t wrap your meal in newspapers), but the idea of yesterday’s headlines sinking into obscurity is still relevant. However, sometimes those headlines reappear prefixed with “Whatever happened to…”

One example we looked at on the blog is the Specification Wars and whether TypeSpec will reignite them. The conclusion (for now) is “no,” but it raises questions about the dominance of OpenAPI and room for other complementary formats. In the spirit of uncovering old headlines comes APIs.json, a format for describing API metadata devised in the early part of the 2010s by API economy leaders Kin Lane and Steven Willmott. The development of the specification has taken a four-year hiatus but is now back with a new version in early 2024.

We’ve discussed APIs.json and the closely related APIs.io on the blog and looked at the features and capabilities that make them useful. However, if APIs.json claims to be a standard that aims to publish machine-readable API metadata, then we should look more deeply at the standard itself and its place in the API economy. We can then ask the question: why should you (or should you not) adopt APIS.json?

Making Practical Use of API Metadata

Many standards in the API economy are described as machine-readable because that feature gives them a raison d’etre. If a given standard cannot be ingested by software tools to create code or annotations, then it relies on the frailties of humans in transposing published data to code, making their adoption less successful.

In this context, the maintainers describe APIs.json, first and foremost, as a standard aimed at machines:

“APIs.json is a machine readable specification that API providers can use to describe their API operations, similar to how web sites are described using sitemap.xml.”

The comparison with a website and sitemap.xml is fair, but the capabilities and possibilities of APIs.json are significantly greater when one considers how API metadata can be put to work. API consumers can potentially leverage APIs.json data in many different ways to dynamically configure an API client:

• Deployment properties such as the URL an API is available at are included in an APIs.json file. This could allow configuration to easily be changed (with, of course, the proper controls and security).
• The behaviors of an API client, such as throttling or smoothing API calls, could be closely modeled on the published capabilities of the API, providing a mature approach to traffic management at the client.
• Standardized references to API documentation can be collected to provide links in platforms like API marketplaces.

APIs.json, therefore, has many use cases and is a very practical way of publishing and consuming data related to APIs. Its capabilities are significant and should benefit API providers and consumers alike. However, its penetration in the API economy is relatively limited, considering these capabilities and how long the standard has existed.

Consensus for the APIs.json Standard

One reason why adoption is limited might be consensus. The value of making practical use of APIs.json is clear. The properties provided in the description are valuable to API consumers. However, the format was not created from a position of consensus. Standards tend to come from large communities with many stakeholders and contributors alike. It is this community that helps drive both development and adoption.

APIs.json is specifically attributed to the two aforementioned leaders in the API Economy (although the commit history shows Nicolas Grenié has also contributed significantly) and, without doubting their brilliance, casting the net wider in terms of contributors would almost certainly foster buy-in to both adopting and evolving the standard.

When you compare APIs.json to other API-related standards, the teams that create them are broad and represent various interests. Standards generally are a broad church. For APIs.json to be as successful as possible, it will mean extending the community to incorporate more interests and views.

Extensibility of the APIs.json Standards

A big part of how standards work is also their extensibility, with a means to address use cases and properties that fall outside the specification. In OpenAPI, for example, Specification Extensions provides a mechanism that implementers and API providers can leverage to add extra information or address unique requirements. This is vital for many vendors as it allows them to both adopt OpenAPI as a description format and extend it to help users configure the tools provided by the vendor. An example of such an implementation is an API gateway: most API gateway vendors who support configuration using an OpenAPI description also implement Specification Extensions.

Providing standardized extensions is generally considered a mixed bag. Of course, it provides the means to tailor your implementation to your needs. However, it can also counter standardization, as it relies on implementers contributing back to the standards when they implement an extension that may be useful to the community. It does, however, set “guardrails” and encourage a common feedback loop from extensions back to the core standard.

At version 0.17 of the APIs.json standard, there is no guidance available in the Extensions section. Implementing guidance on extensions will be critical to implementers picking up APIs.json as it allows them to experiment and grow the standard in a controlled fashion.

Tooling Support for APIs.json

There is then the question of tools that support APIs.json. You could argue, being a JSON format, that having widespread tooling support is unnecessary as JSON is well-supported in almost any programming language. However, manually writing JSON files when they can be generated from tooling is not desirable.

Take the example of API gateways again, and more widely of API management tools. Most API management solutions already hold some of the information that could be provided and exposed as API-related metadata using an APIs.json document. Either hosting the metadata directly using a gateway endpoint or publishing a JSON file, in both cases formatting the metadata using the APIs.json standard, could be done in a trice.

It is also hard to ascertain how many vendors have bought into APIs.json as a format for publishing API metadata. APIs.io uses the format to allow API providers to publish data on the platform and lists a good number of APIs. However, examples of tooling support elsewhere are hard to find. Ideally, an API provider could use APIs.json in the same manner as an OpenID provider publishing discovery metadata, which informs clients of key parameters associated with the OpenID Connect implementation. This would help unlock all the use cases we’ve already described.

What Can APIs.json Do for You?

In our introduction, we asked why you should adopt APIs.json. APIs.json can help you consume API-related metadata and automate many aspects of configuring your API clients. This can be incredibly valuable to how you and your organization operate in the API economy.

However, the community around the APIs.json standard must grow to encourage adoption and help make APIs.json descriptions readily available. The key to the standard’s success is operating at scale and having the means to create documents using tooling. Buy-in is crucial to making this happen. As a minimum, the standard needs the following to be successful in their community:

• Buy-in to the standard and consensus it is right and appropriate.
• Availability of an APIs.json endpoint at API providers.
• Tooling support in the software community.

APIs.json has great promise as a description format for API metadata and meets real needs in the API economy. To fulfill those needs, it needs to grow beyond its current footprint and be embraced more widely in the API community.