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.
Descriptions for APIs
Rules
APIs.json APIs Description Info
Each API included in an APIs.json file should have a 1-3 paragraph description. This description serves as the first impression for potential consumers and is often displayed in portals, networks, ...
Strategies
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,...
Lifecycle
description Definitions Define
The definition is the contract. OpenAPI, AsyncAPI, JSON Schema, and APIs.json are the machine-readable artifacts I use to describe what an API is before, during, and after it exists. Investing in s...
menu_book Documentation Beta
Documentation is the API for humans. I generate reference docs from the definition and surround them with the guides, examples, and getting-started material that turn a spec into understanding. Doc...
travel_explore Discovery Production
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 AP...
