APIs.json
APIs.json is a machine-readable metadata format used to describe APIs (Application Programming Interfaces) and their associated resources. It acts as a discovery format similar to how robots.txt helps search engines discover web pages. The goal of APIs.json is to simplify the process of finding, cataloging, and integrating APIs by providing a standardized way to document the follow details.
- Technical - With APIs.json you can index OpenAPI, but also Postman or Bruno collections, and any other machine-readable artifact that defines the surface area of individual APIs.
- Business - With APIs.json you can index the aspects of API operations that business stakeholders will care most, like discovery, onboarding, billing, and areas more aligned with business.
- Common - Using APIs.json, you can define the technical and business details of each individual API, but also the shared properties available across many APIs in a standardized way.
APIs.json can provide an index for an entire API portal, or a single API in a GitHub repository. APIs.json can be indexed to provide search and discovery for APIs, but also a machine-readable artifact that can be used to govern the operations surrounding APIs. APIs.json is designed to do for API operations, what OpenAPI has done for APIs.
APIs.json is a machine-readable metadata format for describing APIs and the resources that surround them — a discovery index that does for API operations what robots.txt did for web crawlers. Where OpenAPI describes the surface area of a single API, APIs.json describes the whole operation: the specs, documentation, onboarding, pricing, licensing, and support that make an API usable. It can index an entire developer portal or a single API sitting in a GitHub repository.
- A discovery index - A single file that points at all the machine-readable artifacts describing one or many APIs.
- Technical and business properties - Links out to OpenAPI, Postman, and Bruno collections alongside onboarding, billing, and support details business stakeholders care about.
- Common shared properties - Defines properties once and reuses them across many APIs in a portal instead of repeating them.
- Governable, not just discoverable - The same index a crawler uses to find APIs is an artifact you can lint and govern operations against.
APIs.json is the backbone of how I catalog the API landscape across API Evangelist and APIs.io — every provider profile and every artifact behind a listing is indexed through it, which is what lets a search engine or an agent walk from a company to its APIs to the exact spec or workflow it needs. It travels naturally with API Commons building blocks, and in the agentic turn it is the map that tells an agent what exists and where to reach for it before it acts.
Referenced on the API Evangelist blog
Where this standard shows up across sixteen years of my writing at apievangelist.com — how it fits into API design, governance, and the agentic turn.
Related Rules
Every API needs a unique identifier, known as an AID (API Identifier). The APIs.json file, contract, or collection contains its own AID, which the API uses as part of its reference. Additionally, t...
Every API needs a unique identifier, known as an AID (API Identifier). The APIs.json file, contract, or collection contains its own AID, which the API uses as part of its reference. Additionally, t...
Each API defined within an APIs.json artifact can specify the base URL for the API. This URL serves as a reference point for developers during onboarding and when making API calls. Additionally, it...
Each API defined within an APIs.json artifact can specify the base URL for the API. This URL serves as a reference point for developers during onboarding and when making API calls. Additionally, it...
The contact object in an APIs.json file allows for referencing the email address of a person or group. This property provides a convenient way for users to seek support for an API, using email as t...
The contact object in an APIs.json file allows for referencing the email address of a person or group. This property provides a convenient way for users to seek support for an API, using email as t...
The contact object in an APIs.json file allows for associating a vCard that represents an individual or organizational entity. It includes common contact information such as a name, email, or other...
The contact object in an APIs.json file includes a full name (FN) property, which specifies the formatted text corresponding to the contact name in the vCard for an API. This provides a quick and c...
The contact object in an APIs.json file includes a full name (FN) property, which specifies the formatted text corresponding to the contact name in the vCard for an API. This provides a quick and c...
The contact object in an APIs.json file allows for associating a vCard that represents an individual or organizational entity. It includes common contact information such as a name, email, or other...
Each API included in an APIs.json file needs a 1-3 paragraph description. This description serves as the first impression for potential consumers and is often displayed in portals, networks, search...
The humanURL property for each API defined in an APIs.json contract provides a link for business or technical consumers to learn more about the API. This URL can direct users to a portal, documenta...
Each API defined within an APIs.json file can include a dedicated image, offering a visual representation of the resource or capability it provides. This enhances the API's approachability and visu...
The APIs property in an APIs.json file enables the definition of one or more APIs as part of a larger collection. Each API within this property has its own subset of metadata, allowing it to be uni...
Each individual API in an APIs.json collection has its own name property, allowing for a clear description of the API. This name might match the API's title in the OpenAPI Info section, but it coul...
This property ensures provides a reference to an about page, either for the company, organization, or government agency behind an API, or specifically about the domain, team, and the APIs they produce
This so that an API has had the [APIOps Business Impact Canvas](https://www.apiopscycles.com/resources/business-impact-canvas) applied to the API, requiring that the canvas is present in the reposi...
This so that an API has had the [APIOps Business Model Canvas](https://www.apiopscycles.com/resources/api-business-model-canvas) applied to the API, requiring that the canvas is present in the repo...
This so that an API has had the [APIOps Capacity Canvas](https://www.apiopscycles.com/resources/capacity-canvas) applied to the API, requiring that the canvas is present in the repository and regis...
This so that an API has had the [APIOps Customer Journey Canvas](https://www.apiopscycles.com/resources/customer-journey-canvas) applied to the API, requiring that the canvas is present in the repo...
This so that an API has had the [APIOps Domain Canvas](https://www.apiopscycles.com/resources/domain-canvas) applied to the API, requiring that the canvas is present in the repository and registere...
This so that an API has had the [APIOps Event Canvas](https://www.apiopscycles.com/resources/event-canvas) applied to the API, requiring that the canvas is present in the repository and registered ...
This so that an API has had the [APIOps Interaction Canvas](https://www.apiopscycles.com/resources/interaction-canvas) applied to the API, requiring that the canvas is present in the repository and...
This so that an API has had the [APIOps Locations Canvas](https://www.apiopscycles.com/resources/locations-canvas) applied to the API, requiring that the canvas is present in the repository and reg...
This so that an API has had the [APIOps Locations Canvas](https://www.apiopscycles.com/resources/rest-canvas) applied to the API, requiring that the canvas is present in the repository and register...
This so that an API has had the [APIOps Value Proposition Canvas](https://www.apiopscycles.com/resources/api-value-proposition-canvas) applied to the API, requiring that the canvas is present in th...
This property so that an API has operational level rules for APIs
This property so that there is a link to the validator for the APIs
This property so that there is a human readable authentication page available that will provide what type of authentication is used and how it can be applied, as well as any services or tooling tha...
This property so that blogs in support of APIs have an Atom or RSS feed of posts, allowing for the syndication of updates and information around individual APIs and the operations around them
This property so that an API has a reference to a blog where anyone can find updates and other stories that will help keep API consumers and other stakeholders up to speed on what is happening with...
This property so that than an individual API or API operations possesses a change log that catalogs all the changes that have occurred in a recent time frame, with historical and version informatio...
This property so that an API has the ability to compare two different versions of an API and see what the difference are between them
This property so that an API has a deprecation policy shared as part of the contract, communicating what the lifespan of APIs are, each individual version, as well as communication around the depre...
This property so that there is documentation published for an API, and API consumers will have a set of human-readable instructions for onboarding and integrating with HTTP APIs in their applications
This property so that there is a production environment available for an API, giving base URL, tokens, keys, and other key / value pairs that are needed to integrate with an API
This property so that there is a staging environment available for an API, giving base URL, tokens, keys, and other key / value pairs that are needed to integrate with an API
This property so that an API has a reference to a examples for individual APIs or as part of common properties, giving examples and synthentic data that can be used for APIs.
This property so that there is an email available for API consumers to provide feedback
This property ensures there is a URL to Git issues specifically for giving feedback
This property so that there is a link to a discussion forum, giving a way for consumers and producers to engage and support either other throughout the lifecycle
This property so that there is a reference to the gateway for an API, referencing where you can manage the configuration for each API
This property so that there is a getting started link available, giving a reference for API consumers to get started with an API is as few steps as possible
This property so that a GitHub Actions CI/CD pipeline is available for an API, giving a link to the pipeline YAML artifact, which can be used to automate and govern the API as part of the build pro...
This property so that an API is associated with GitHub organization, giving the URL to where you can engage with the operations surrounding an API
This property so that an API possess a reference to a dedicated GitHub repository that is used to manage the Open, but also possible server and client code
Each individual API included in an APIs.json file can have a properties collection, which contains specific properties relevant to that API. These properties often start with human-readable element...
This property defines an Insomnia collection available for each API, giving executable artifacts that can be used in the Insomnia client for making calls, and executing automation workflows
This property so that an API Commons interface license exists for an API, giving a machine-readable reference for an API, as well as data, backend, and front-end code
This property makes sure there is an API lifecycle schema defining all of the stages of a lifecycle and which policies get applied at each stage of the API lifecycle
This property so that an API has a reference to a mock servers for individual APIs or as part of common properties, giving mocked deployments of an API that can be used for making test API calls.
This property so that there is an OpenAPI present for an API, giving the technical contract that describes the surface area of an API
This property so that an OpenAPI has support governance rules, that can be applied during design time via editors, development time via IDE, and run-time via CI/CD pipelines
This property so that there is a link to the validator for the OpenAPI technical contract, allowing anyone to see the details of governance being applied
This property so that an API has performance testing in place, giving a URL to the performance testing, dashboard, or other resource
This property provides a link to the dedicated plans page that applies to an API, giving information about access tiers, rate limits, and features available for an API as part of a wider API busine...
This property ensures there is a governance policies reference as part of an API contract, usually a common property pointing to a centralized set of policies that get applied
This property ensures there a developer portal associated with an API and that you can find a landing page for the API, documentation, SDKs, and other resources
This property so that an API has at least one Postman Collection associated with it, giving automation, tests, and other executable derivatives of an APIs OpenAPI
This property so that an API is associated with a Postman Workspace, giving a single location that API producers and/or API consumers can engage around an API
This property provides a link to a pricing page that applies to an API, giving a breakdown of the costs associated with using an API
This property provides a link to the privacy policy for an API, giving the legal details of how privacy is approached for each API
This property so that an API has a dedicated link to Git issues for asking questions
This property ensures there is an API rate limits reference associated with API, making sure the rate limits applied to an API are clearly communicated
This property ensures there is a reference to the road map for an API or for the entire API operations within domain, line of business, or teams
This property so that an API has governance rules applied, usually as part of a central set of governance rules, defined by policy, or stages of the API lifecycle
This property so that an API has a reference to a sandbox for individual APIs or as part of common properties, giving sandbox, synthetic data, and mock servers for use in making test requests.
This property so that there is a Go SDK available for an API, making it easier for Go developers to integrate an API into their applications
This property so that there is an SDK available for an API, making it easier for developers to integrate an API into their applications
This property so that there is a Java SDK available for an API, making it easier for Java developers to integrate an API into their applications
This property so that there is a Node SDK available for an API, making it easier for Node developers to integrate an API into their applications
This property so that there is a Python SDK available for an API, making it easier for Python developers to integrate an API into their applications
This property ensures there is a URL to the security page, giving details about how security is handled for an API
This property ensures there is a link to where you sign up for an API, making sure API consumers can access in a single click
This property so that there is a status page available for each API, giving the uptime status for any given moment, as well as historical data
This property so that an API has email support, giving a valid email address that can be used to get API support
This property so that there are Git issues available to support an API, using the issues capability of GitHub, GitLab, or Bitbucket to support API consumers
This property so that there is a support page available for an API, giving direct and in-direct support opportunities for each API or for entire API platform
This property so that there is a reference to the team behind an API, giving a reference to business and engineering stakeholders
This property so that an API has a reference to a terms of service, covering the legal side of using an API
This property so that properties of an API or API contract all have valid URLs, checking if any of the URLs are not properly formed, or could be other formats
This property ensures there is a reference to the use cases for an API, helping align an API with the who, what, how, and why of putting an API to work
This property ensures there is a reference to how APIs are versioned, giving a single place where teams can learn about how change is communicated
This property ensures there is a reference to a video page or channel for an API
This property so that there is a centralized vocabulary in use for guiding the creation and usage of tags, path segments, and other metadata associated with an APIs
Each API defined in an APIs.json artifact includes a property for adding one or more tags. These tags provide additional context about the resources or capabilities offered by the API, highlighting...
Each API defined in an APIs.json artifact includes a property for adding one or more tags. These tags provide additional context about the resources or capabilities offered by the API, highlighting...
Maintaining consistent casing for tags applied to individual APIs ensures a uniform appearance and enhances search and discovery. Each word in a tag needs to be capitalized, with the first letter o...
Maintaining consistent casing for tags applied to individual APIs ensures a uniform appearance and enhances search and discovery. Each word in a tag needs to be capitalized, with the first letter o...
An APIs.json artifact can include a set of common properties that describe aspects of API operations shared across multiple APIs in a collection. These common properties are typically managed by a ...
The created property in an APIs.json contract might seem like a minor detail, but it serves an important purpose by giving a timestamp that marks the origin of the intent to offer an interface for ...
Every collection of APIs defined in APIs.json needs to include a one- or two-paragraph description outlining the purpose of the APIs. While individual APIs needs their own descriptions, the collect...
APIs.json contracts are often used to power discover and distribute as part of API catalogs and marketplaces. These are places where having a visual representation matching the purpose of a collect...
The maintainers email is to provide a quick way to contact the maintainer of an APIs
The purpose of the FN is to specify the formatted text corresponding to the contact name in the vCard for an APIs
The maintainers property is for identifying the entity who is maintaining an APIs
The modified property in an APIs.json collection indicates the most recent updates made to a group of APIs. While detailed change logs can provide more specifics, an accurate and up-to-date modifie...
The name of a collection of APIs should describe their purpose, target audience, and the problems they aim to solve. While individual APIs needs their own specific names, the name in the APIs.json ...
Every collection of APIs needs a unique identifier. This unique API identifier, or AID, serves as a human and machine-readable reference for organizing and managing various APIs. Similar to a barco...
The type property in an APIs.json file classifies the business contracts for different types of API collections. It can represent a simple index for a single API, a template or example to showcase ...
The specification version of an APIs.json collection indicates which version of the APIs.json specification is being used. This ensures compatibility and allows for the validation of new properties...
Each collection of APIs defined in an APIs.json artifact includes a property for adding one or more tags. These tags provide additional context about the resources or capabilities offered as part o...
Maintaining consistent casing for tags applied to APIs.json contracts ensures a uniform appearance and enhances search and discovery. Each word in a tag needs to be capitalized, with the first lett...
Maintaining consistent casing for tags applied to APIs.json contracts ensures a uniform appearance and enhances search and discovery. Each word in a tag needs to be capitalized, with the first lett...
The top-level URL in an APIs.json file contains a fully qualified link to where the APIs.json file is published. This URL serves as a reference for the API collection and can also be validated. Whe...
