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
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...
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...
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
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...
Blog Feeds
Blog feeds let you push updates out to where producers and consumers already are. RSS and Atom are old-school building blocks, but they still work well for syndicating API news without requiring pe...
Blogs
A blog gives you a steady channel for telling stories about your API. It keeps producers and consumers engaged with regular updates and creates a narrative around what is happening and why it matters.
Descriptions for APIs.json Contracts
API contracts need good descriptions just like the APIs themselves do. A solid description of the contract gives stakeholders the context they need to understand what they are looking at.
Images for APIs.json Contracts
Adding images to your API contract metadata might seem minor, but it makes APIs more recognizable across portals, docs, and catalogs. Visual identity matters at scale.
Names for APIs.json Contracts
Naming your API contract well is about defining scope. A clear, descriptive name tells people exactly what bundle of APIs they are looking at and what domain it covers.
Tags for APIs.json Contracts
Tags on your API contracts serve the same purpose as tags on individual APIs. They create bounded context, organize by domain, and make discovery possible at the contract level.
Unique Identifiers for APIs.json Contracts
Unique identifiers for your API contracts and the APIs they contain give you the reference points you need for automation, discovery, and governance at scale.
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.
Documentation
Documentation is the human-readable representation of your API's surface area. Paths, methods, descriptions, examples -- this is where consumers go to understand what is possible and how to get sta...
Getting Started
Getting started is the single most important thing you can get right for new API consumers. A simple, plain language walkthrough that covers discovery, onboarding, and first API call makes or break...
GitHub Organizations
A GitHub organization is the workspace where API operations happen. Source control, CI/CD, teams, and collaboration all come together here as the backbone of how APIs get produced and managed.
GitHub Repository
The GitHub repository is the single source of truth for an API contract. OpenAPI, road map, change log, support -- everything lives here, and it is where the real work of producing APIs happens.
Governance
Governance is how you get hundreds of APIs moving in the same direction. It is not about control -- it is about a common platform, lifecycle, policies, and rules that help teams ship consistent API...
How Will API Be Used
Understanding how consumers will actually use an API gets into the details of programming languages, frameworks, and integration patterns. This is where abstract capabilities become real implementa...
Contact Information for APIs
Contact information in your OpenAPI info section tells consumers who to reach out to. It is a small detail that makes a big difference when someone is stuck or has a question.
Description of APIs
The description in your OpenAPI info block is prime real estate. This is where you tell consumers what the API is about in a way that makes them want to keep reading.
License for APIs
Including a license in your OpenAPI info section makes the legal terms explicit. I see way too many APIs where consumers have no idea what they are legally allowed to do.
Terms of Service for APIs
Terms of service linked from your OpenAPI info give consumers the legal context they need. Making this part of the technical contract means it travels everywhere the spec goes.
Title of APIs
The title in your OpenAPI is the name that shows up everywhere -- in docs, catalogs, and code generation. Getting the casing, length, and clarity right here sets the tone for everything.
Version of APIs
Version information in your OpenAPI tells consumers which release they are looking at. Whether you use semantic versioning or date-based, having it in the spec is how you communicate where things s...
Operation Tags
Tags on operations organize endpoints into logical groups. They drive how documentation is structured and how consumers discover related functionality within an API.
OpenAPI Tags
Tags at the OpenAPI level organize your API into logical groups. They need names, descriptions, and consistent casing to actually serve their purpose in documentation and discovery.
OpenAPI
OpenAPI is the technical contract that describes the surface area of each API in a machine-readable way. Documentation, SDKs, testing, and governance all flow from this single artifact.
Portals
Developer portals bring together documentation, sign-up, getting started, plans, and SDKs in one place. Whether public or private, a dedicated portal is how you make the API experience accessible.
Postman Collection
Postman Collections give you an executable, machine-readable representation of your API. They make it possible to test, explore, and share API interactions in a way that OpenAPI alone does not cover.
Postman Workspace
Postman Workspaces provide a collaborative space for managing API contracts alongside GitHub. Private, partner, and public workspaces let you control access while keeping everything organized.
Standards
Standards are the building blocks that save everyone time and money. HTTP, JSON, OpenAPI, JSON Schema -- adopting these keeps APIs consistent and interoperable without reinventing the wheel.
Support
Support is one of those things that separates APIs that get adopted from ones that get abandoned. Making it clear how consumers can get help -- email, tickets, forums -- is essential.
Use Cases
Use cases are the who, what, how, and why of an API. Documenting and maintaining them keeps the API aligned with real business needs rather than drifting into features nobody asked for.
Videos
Videos are an engaging way to demonstrate how an API works, share updates, and provide walkthroughs. They complement written docs and reach people who learn better by watching.
What Will Be Done With API
Understanding what consumers will build with an API shapes everything from design to documentation. If you do not know what people will do with your resources, you are building in the dark.
Who Will Be Using API
Knowing who is using your API -- the actual people and their contexts -- is fundamental. If you do not understand your consumers, you can not design an API that works for them.
Why Will API Be Used
The why behind API consumption is the business case. Understanding why consumers integrate with your API tells you whether you are delivering real value or just providing a technical capability nob...
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.
Interactive Documentation
Interactive documentation with try-it-out functionality lets consumers test API calls right from the docs. This removes the gap between reading about an API and actually experiencing how it works.
Strategies
API Paths Must Conform to the Organization
Your API paths are the most visible thing you put out there, and when they don't follow any organizational standard, the whole thing feels like a junk drawer. I keep finding APIs where every team i...
API Responses Must Be Meaningful and Consistent
I keep seeing APIs where responses feel like a total afterthought. Inconsistent structures, missing status codes, no examples. The reality is your responses are the conversation you are having with...
APIs Are Aligned with Industry Using Standards
Before you go inventing a new schema or process, look at what already exists. I have watched so many teams reinvent the wheel when perfectly good standards were sitting right there waiting to be us...
APIs Are Always Aligned with the Wider Enterprise
Every API needs a real business use case that ties the technical details back to why the enterprise actually cares. I see too many APIs built because someone thought it would be cool, with zero ali...
APIs Are Always Well Documented
Documentation is the front door to your API, and I am still amazed at how many teams leave that door half open. Or locked. You need human-readable docs that cover methods, operations, requests, res...
APIs are Defined as API Contracts
I think of API contracts as the thing that bridges the business and technology sides of what we do. When you define APIs as contracts and manage them in source control, you can track not just the t...
APIs are Defined by Technical Contracts
Every API needs machine-readable artifacts that define what it actually does. OpenAPI, JSON Schema--these make your APIs tangible, testable, and discoverable. Without them, you are just describing ...
APIs Are Made Available Through a Platform Gateway
Gateways are one of the most important pieces of the puzzle, and every API should be deployed through one. Development, staging, production--each environment with a common set of policies for acces...
APIs Are Part of Regular Active Communication
APIs do not exist in a vacuum. The teams that treat communication as an afterthought are the ones whose consumers are always blindsided by changes. Road maps, change logs, blog posts, videos--weave...
APIs Must Be Actively Governed
Governance is what keeps things from turning into chaos, but it only works when it is active and ongoing. Not a document someone wrote two years ago. You need a common lifecycle, policies and rules...
APIs Must Be Supported and Have Feedback Loops
Support and feedback loops are what keep the relationship between producers and consumers healthy. Self-service support channels, direct support options, and regular feedback mechanisms that go bey...
APIs Must Reusable Whenever Possible
Reusability is one of those things that separates mature API operations from everyone else. When you make schema, parameters, examples, and error responses modular and interchangeable--not just wit...
APIs Operations Possess Dedicated Workspaces
Workspaces are the virtual factory floor where the real work happens. Every domain, line of business, and team needs a dedicated one. This is where collaboration and automation actually take place....
APIs Possess Informative Metadata
Metadata is what makes APIs findable and understandable. It is not just technical details--it is the business context that tells consumers what an API does and why they should care. Good metadata m...
Data Should Be Well-Defined and Validated
The schema behind your APIs is where the rubber meets the road. If your data does not have a well-known shape, if it is not validated on the way in and out, you are setting consumers up for surpris...
Onboarding is Always as Easy as Possible
I have been onboarding with APIs for over fifteen years and the best ones always get you from zero to first call in just a couple of steps. Documentation, authentication, SDKs--these need to be eas...
Operations Must Always Be Secure
Security is not something you tack on at the end. It has to be woven into design, development, and run-time from day one. Data, credentials, logs--everything needs to be locked down and operating a...
Operations Must Be Useful and Consistent
Every API operation should do one thing and do it well. That is the Unix philosophy applied to APIs and it still holds up. When your operations follow common standards with consistent naming, clear...
Producing APIs MUST Be Repeatable
If you can't reproduce how an API was built, you don't have a process. You have tribal knowledge. A single source of truth for artifacts and conversations, backed by CI/CD pipelines that make deliv...
APIs Deliver an Exceptional Developer Experience
Developer experience is where the technology, business, and politics of APIs all converge. Interactive docs, sandbox environments, realistic examples, intuitive naming--when developers can quickly ...
APIs Are Discoverable Through a Central Catalog
If people can't find your APIs, they will build their own--and that is how duplication spirals out of control. A central catalog with consistent metadata, tags, and descriptions is one of the most ...
API Info and Metadata Is Complete and Accurate
The info object in your OpenAPI definition is the first thing both humans and machines encounter, and I am constantly surprised by how often it is incomplete. Title, description, version, contact, ...
