Discovery is how APIs get found and reused instead of rebuilt. APIs.json, catalogs, and search make the APIs I operate visible to the people who need them. Good discovery is what turns a pile of APIs into an actual platform.
Discovery
Production
Stop 22
Policies at this stop
Agent Readiness with agents.md
I require that every API provider ships an agents.md file that tells an automated consumer exactly how to behave when working with the API, including the conventions, the guardrails, and the workfl...
Agent Readiness with llms.txt
I require that every API publishes an llms.txt file at a predictable, well-known location so that large language models and the agents built on them can find a concise, curated map of what the API ...
Descriptions for APIs
Providing a robust description of each API, providing the right amount of information for consumers to understand what is possible and what the business use case is.
Images for APIs
Including images as part of the metadata for your APIs helps make APIs more visible as part of portals, documentation, and other resources.
Names for APIs
Providing a clear, descriptive, and concise name for each API, as well as the APIs it contains, properly defining the scope, with an intuitive first impression of an API.
Tags for APIs
Tags provide a bounded context for your APIs, providing keywords that help organize APIs by domains, and make them more discoverable.
Unique Identifiers for APIs
Providing unique identifiers for API apis, as well as the APIs that are indexed as part of an API, providing a key reference for discovery and automating around a contract.
Metadata for APIs
Unique identifier, name, description, tags, and other metadata for the API that defines the purpose of each individual API, and how it benefits API producer and consumers, establishing the base of ...
Arazzo Workflows Provided
Require that APIs which chain multiple operations to accomplish real work provide Arazzo workflow definitions describing those sequences. I want the multi-step paths a consumer must follow, the ord...
Base URL for API
Providing a valid URL to the base for an API that is designed for machines to use when making call to an API by an consumer.
Data Portability Provided
Require that consumers can export their data from an API in a portable, standard format without friction or penalty. The data flowing through an API belongs to the people and organizations it descr...
Event Types Cataloged
I require that every event an API emits is enumerated in a published catalog of event types, each with a stable name, a described payload, and a clear meaning, so consumers know exactly what can ha...
API Catalog (Experience)
Require that every API is registered in a central, searchable catalog with enough metadata that a developer can find it, understand it, and decide to use it without asking anyone. I care deeply abo...
How Will API Be Used
How will consumers be putting API resources and capabilities, getting into the details of programming languages and frameworks.
Human URL for APIs.json Contract
Providing a valid URL to a landing page for the API that is designed for humans to use when learning more about an API.
Procurement Evaluation Checklist
Require that every API considered for adoption be run through a documented procurement evaluation checklist before a team commits to it. I want the same questions asked each time, covering security...
Reuse Scoring Applied
Require that every API carry a reuse score that measures how widely and effectively it is being reused across teams and how much it duplicates existing capabilities. I want reuse assessed with a co...
Use Cases
The who, what, how, and why of producing an API, making sure all of the known use cases are accurately described and kept up to date, then used to ensure each API is delivering what is expected wit...
What Will Be Done With API
What will consumers be building with the resources and capabilities being made available via APIs.
Who Will Be Using API
Who is using an API, focusing on the people who will be putting an API to work in their applications.
Why Will API Be Used
What are the reasons an API consumer will be putting APIs to work in their applications and integrations as part of their business.
