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, reducing duplication and improving reuse across the organization.
APIs Are Discoverable Through a Central Catalog
Policies
API Catalog
An API catalog is the front door to your API program. If consumers can not discover and search for APIs with consistent metadata, they will never know what is available to them.
Metadata for APIs
Metadata is the foundation of your API contract. The name, description, tags, and identifiers tell producers and consumers what this API is about and why it exists. Without solid metadata, everythi...
Names for APIs
The name of your API is the first thing anyone sees. If it is vague or overly technical, people move on. A clear, concise name sets the right expectation about what the API does and the scope it co...
Descriptions for APIs
I can't tell you how many APIs I come across that have no description or just a couple words that tell you nothing. A good description helps consumers understand what an API does and why they shoul...
Images for APIs
Images seem like a small thing, but when you are browsing through a catalog of hundreds of APIs, having a visual identity for each one makes a real difference in how discoverable and memorable they...
Tags for APIs
Tags are one of those simple building blocks that do a lot of heavy lifting. They give your APIs a bounded context, help organize things by domain, and make it way easier for people to find what th...
Unique Identifiers for APIs
Every API needs a unique identifier. Without one, you can't reliably reference it in discovery, automation, or governance. It is the key that ties everything together across the contract.
Metadata for APIs.json Contracts
The metadata on your API contract is the first handshake with anyone who encounters it. The identifier, name, description, and tags establish what this agreement is about and who it serves.
Experiences
Discovery
Discovery is the dark matter of the API landscape. Teams build APIs that already exist somewhere else, and consumers can't find the APIs they need. Without a catalog and proper metadata, you're jus...
Onboarding
I see teams dealing with massive friction during onboarding. If a consumer can't get from zero to their first successful API call in minutes, you've already lost them. Getting started guides, sandb...
Self-Service
Self-service is the goal I keep pushing teams toward. If a consumer can't find your API, sign up, get keys, and make their first call without emailing someone, you've created a bottleneck that will...
Reusability
I watch teams rebuild the same patterns, schemas, and components from scratch over and over again. Reusability is one of the promises of APIs that we still haven't delivered on, and it's where a lo...
Alignment
I see product and engineering teams talking past each other constantly when it comes to APIs. Without alignment on the why behind each API, you end up with technically sound resources that nobody a...