The average enterprise maintains approximately 0.5 APIs per employee, making it a constant challenge to track the growing inventory of HTTP APIs being produced and consumed. Enterprises often address this challenge by publishing catalogs, marketplaces, and portals to facilitate API discovery. Standards like APIs.json are also emerging to support centralized discovery while enabling more federated, distributed, and ad hoc approaches. API discovery can be partially addressed by publishing APIs to a catalog or marketplace when they are deployed via an API gateway. However, this approach primarily focuses on produced APIs. Ideally, both produced and consumed APIs should be actively indexed, aggregated, and made searchable and browsable. API distribution and discovery should not only be a core aspect of producing APIs but also an integral part of integrating any API into applications or systems.
Discovery
Properties
Policies
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 ...
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 ...
Blog Feeds
A blog RSS or Atom feed provides a simple way to syndicate information and updates about APIs with producers and consumers, allowing it to be pushed out to where they are located and regularly cons...
Blogs
A blog helps provide a regular channel for publishing relevant stories and information for both producers and consumers of an API, providing a simple, informative, and recurring way to stay in enga...
Metadata for APIs.json Contracts
Unique identifier, name, description, tags, and other metadata for the contract that defines the purpose of the API Contract, and how it benefits API producer and consumers, establishing the base o...
Hypermedia (Design)
Require that APIs return links alongside their data where it helps consumers navigate related resources, discover available actions, and follow state transitions without hardcoding URLs. APIs shoul...
URL Structure (Design)
Require that every API uses a consistent, predictable URL structure, with clear resource hierarchies, sensible pluralization, and paths that read like the nouns of the domain rather than a grab bag...
Documentation
The human-readable HTML, Markdown, or PDF representation of the technical surface area of each API, providing path, methods, summaries, description, examples, and the other resources consumers will...
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...
Getting Started
The step by step walk-through for new API consumers, ensuring they have exactly what is needed to discover and onboard, but also help make sure the getting started steps are as simple, plain langua...
GitHub Organizations
A GitHub organization provides a dedicated workspaces for teams to produce APIs, organize all the API contracts in motion, and leverage source countrol, CI/CD, teams, and other resources provided b...
GitHub Repository
A GitHub repository for an API, providing the single source of truth for the API contract, OpenAPI, and other artifacts, as well as the road map, change log, support, feedback, and other elements o...
Governance
Governance standardizes APIs across teams using a common platform and lifecycle, applying governance policies and rules, and keeping everyone moving in the same direction using common guidance.
Servers (OpenAPI)
Require that every OpenAPI definition declares its servers, the concrete base URLs where the API actually lives, ideally with an entry for each environment so production and sandbox are both discov...
OpenAPI
A machine-readable OpenAPI using the most recent version of the API specification, describing the surface area of each API, which is then used to render the human-readable documentation, and other ...
Portals
Dedicated developer portals for an API provide a way to make documentation, sign-up, getting started, plans, SDKs, and other resources API consumers need more easily accessible publicly or privatel...
Postman Collection
A machine-readable Postman Collection describing the surface area of the API contract or providing more modular and executable representations of portions of the API contract. - Postman - Executable
Postman Workspace
A Postman Workspace provides a dedicated space to manage API contracts within a domain, complimenting other types of workspaces, allowing for private, partner, and public workspaces to exist for ma...
Standards
Internet, industry, market, and government standards help make APIs more consistent, but also save time and money for both producer and consumer, while keeping APIs better aligned with existing ind...
Support
Outline what support is available for API consumers, including email, tickets, forums, and paid support services, making it easy for API consumers to understand how they can get the help they need ...
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...
Videos
Videos offer an engaging way to provide information and updates with producers nad consumers of APIs, demonstrating how an API can be used, providing webinars, workshops, and other useful videos ab...
Strategies
API Info and Metadata Is Complete and Accurate
All OpenAPI definitions must have complete info objects including title, description, version, contact information, license, and terms of service, providing both humans and machines with the contex...
API Paths Must Conform to the Organization
All API paths must conform to the overall organizational domain standards, utilizing plain language and a resourceful approach to delivering digital resources and capabilities via HTTP APIs, provid...
API Responses Must Be Meaningful and Consistent
All API responses should follow Internet, industry, and enterprise standards, providing a meaningful and consistent communication and structure, always providing what was intended for API consumers...
APIs Are Aligned with Industry Using Standards
All APIs must be using relevant Internet, industry, and government standards available, ensuring to properly research areas of operations to see what existing standards may exist before the creatio...
APIs Are Always Aligned with the Wider Enterprise
All API contracts must have use cases that align the business reasons why an API is being delivered to consumers with the actual technical details of each API contract, ensuring that operations all...
APIs Are Always Well Documented
All APIs must have human-readable documentation that defines the technical surface area of each API being made available to API consumers, providing a simple, intuitive, and ideally interactive HTM...
APIs are Defined as API Contracts
All APIs are defined as API contracts so that we can align both the business and technology of delivering consistent high quality APIs, employing source control to manage the technical, but also th...
APIs are Defined by Technical Contracts
All APIs must have machine-readable artifacts that defines the technical surface area of each API being made available to API consumers, utilizing open-source community specifications like OpenAPI ...
APIs Are Discoverable Through a Central Catalog
All APIs must be registered in a central catalog or registry with consistent metadata, tags, and descriptions, ensuring that producers and consumers can find existing APIs before building new ones,...
APIs Are Legible to Automated Consumers
I want our APIs to be legible to the automated consumers reading them, not just to the humans who wrote them. That means operations that describe themselves clearly, tool definitions that spell out...
APIs Are Made Available Through a Platform Gateway
All APIs must be deployed through a common platform gateway established for the domain, line of business, or team, leveraging development, staging, and production environments, and a common set of ...
APIs Are Part of Regular Active Communication
All APIs are considered and included as part of regular internal and external communication channels, sharing road maps, change logs, blog posts, videos, and other relevant information that produce...
APIs Are Ready for AI Agents
I want every API we operate to be ready for the agents that are now showing up as first-class consumers alongside our human developers. That means our APIs publish the machine-readable signposts ag...
APIs Deliver an Exceptional Developer Experience
All APIs must prioritize the developer experience by providing interactive documentation, sandbox environments, realistic examples, and intuitive naming, ensuring that developers can quickly unders...
APIs Must Be Actively Governed
All APIs being produced must be governed as part of the overall strategy, using the platform, as well as a common API lifecycle, applying policies and rules, and keeping teams moving in the same di...
APIs Must Be Supported and Have Feedback Loops
All APIs must have support mechanisms to ensure API consumers have self-service or direct support channels, as well as regular feedback loops for soliciting feedback or answering specific API quest...
APIs Must Reusable Whenever Possible
The components of any API should be made modular and reusable whenever it makes sense to the business use case, keeping schema, parameters, examples, error responses, and other common parts of an A...
APIs Operations Possess Dedicated Workspaces
API operations should provide dedicated workspace for domains, lines of business, and teams who are producing APIs, providing a dedicated location where work, collaboration, and automation can occu...
APIs Possess Informative Metadata
All APIs possess metadata that is relevant to what APIs do, but also how they can be used in business by API consumers, and metadata helps ensure that the front door for API operations within this ...
Data Should Be Well-Defined and Validated
The schema for data that is sent and received via API should always be well-defined, possess a well-known shape, and always be validated, ensuring that digital resources and capabilities are what t...
Onboarding is Always as Easy as Possible
API operations is made easier by making common elements like documentation, authentication, SDKs easy to find and available as just a couple of simple steps that API consumers can follow when it co...
Operations Must Always Be Secure
Individual API operations should always be properly secured during design, develop, and run-time, making sure data, credentials, logs, and all other related resources are properly secured and opera...
Operations Must Be Useful and Consistent
All individual API operations must be useful and follow consistent Internet, industry, and enterprise standards, providing a simple and relevant HTTP API operation that does one thing and does it w...
Producing APIs MUST Be Repeatable
All APIs must have a single source of truth for all artifacts, as well as the conversations and always be able to be delivered using a repeatable process, leveraging existing software development i...
