APIs.json is the discovery specification I created, and it’s one of the things I’m proudest of even though it never achieved the adoption I hoped for. APIs.json is a machine-readable format that lets an API provider publish a small index file describing their APIs and all the operations around them — the documentation, the OpenAPI definitions, the terms of service, the pricing, the support channels, the everything. The idea, which I’ve carried for over a decade, is that discovery should be decentralized: instead of a central directory that someone has to maintain, every provider publishes an APIs.json file at a well-known location on their domain, and the index of the API economy emerges from what providers publish rather than from what a central authority catalogs. It’s the sitemap-for-APIs idea made real, and I still believe it’s basically the right design for how API discovery should work.
The sitemap analogy is where APIs.json started, and it’s the cleanest way to understand it. I wrote in 2013 about a sitemap for APIs — the recognition that the web solved its own discovery problem with sitemap.xml, a file every site publishes that search engines crawl, and that APIs needed the same thing. APIs.json is that file for APIs: a standardized, machine-readable index that points to everything about a provider’s APIs, published at a predictable location so it can be discovered and crawled. The five-month journey toward a stable APIs.json discovery format, which I documented in 2014, was the work of turning that analogy into an actual, usable specification — defining the properties, the structure, the conventions that would let APIs.json files be produced and consumed reliably. What exactly is APIs.json, which I explained in 2015, comes down to this: an open format for making APIs and their operations discoverable, the way sitemaps made web pages discoverable.
The distributed-transport-layer vision is the ambition behind APIs.json, and it’s bigger than just discovery. I wrote in 2015 about APIs.json as a distributed transport layer for the API economy — the idea that if every provider published a machine-readable index of their APIs and operations, you’d have a decentralized, emergent map of the entire API economy that anyone could build on. APIs.io, the search engine I built on top of APIs.json, was the demonstration: crawl the published APIs.json files, index them, and let people discover APIs through a search engine populated by what providers publish rather than what an editor catalogs. This is the GET /apis vision — discovery that scales because it’s decentralized, the way the web itself scales, with the index emerging from distributed publishing rather than centralized curation. APIs.json was meant to be the connective tissue that let the API economy describe and discover itself.
The crucial distinction I had to keep making is that APIs.json is an operations format, not a definition format — it doesn’t compete with OpenAPI. I wrote in 2018 about sharing the APIs.json vision again, clarifying that APIs.json sits at a different layer than OpenAPI. OpenAPI describes a single API’s interface — its operations, schemas, and responses. APIs.json describes everything around the APIs — which APIs exist, where their OpenAPI definitions are, where the documentation is, what the terms are, who supports them. They’re complementary: APIs.json indexes and points to the OpenAPI definitions and all the other operational artifacts, while OpenAPI describes the individual APIs. In the layered specification onion, APIs.json is the outermost layer — the discovery and operations index — with OpenAPI and JSON Schema beneath it describing the individual APIs and their data. Understanding APIs.json means understanding that it operates at the portfolio and discovery level, not the individual-API level.
The properties and evolution of APIs.json are where it matured into a genuinely useful tool, and I kept extending it. I wrote about the APIs.json property types, the includes and network properties that enable federated discovery across linked indexes, the search metadata and ratings, and the operational API rules that APIs.json can carry. The includes and network properties matter especially — they let APIs.json files reference and link to each other, creating a federated, distributed network of indexes rather than isolated files, which is exactly how decentralized discovery has to work. By 2024 I was using APIs.json to drive operational governance, profiling, and rules across API portfolios — because once you have a machine-readable index of all your APIs and their operations, you can apply governance, monitoring, and discovery against the whole portfolio programmatically. APIs.json grew from a simple discovery index into the operational backbone for managing and governing API portfolios at scale.
The honest reckoning with APIs.json is that it didn’t conquer the world despite being, I still believe, the right design — and the reasons why are the deepest lesson in the whole discovery story. The technology worked. The specification was sound. The problem was incentives: providers didn’t publish APIs.json files because the benefit of discovery is diffuse and collective, while the cost of publishing falls on the individual provider. This is the classic commons problem that has haunted API discovery from UDDI onward — discovery is a public good, and public goods are chronically under-provided because no individual party has a strong enough reason to contribute. But I haven’t given up on APIs.json, and the agent era may finally vindicate it. APIs.io and APIs.json goodness came back, as I wrote in 2023, and the work continues, because the machine-readable, decentralized, self-describing discovery that APIs.json provides is exactly what AI agents need to find and understand APIs at runtime. The discovery infrastructure I built a decade early — a standard way for the API economy to describe and discover itself — turns out to be precisely what the agentic future requires. If agents make decentralized, machine-readable API discovery economically necessary in a way human developers never quite did, then APIs.json might finally get the adoption the commons always needed. That would be a fitting resolution to one of the longest-running projects of my career — the format I created to let the API economy describe itself, finding its moment when the consumers became machines that genuinely need it.
References
- Sitemap For APIs
- The Five Month Journey Toward A Stable APIs.json Discovery Format
- What Exactly Is APIs.json?
- APIs.json As A Distributed Transport Layer For The API Economy
- What Is APIs.json And What Is Next For The API Discovery Format
- Sharing The APIs.json Vision Again
- APIs.io APIs.json Goodness Is Back
- Operational API Rules Using APIs.json
- APIs.json APIs, Includes, And Network Properties
