We Can Describe an API. But How Do We Describe an API Product?
Why API products need a shared machine-readable foundation before they need another management platform.
OpenAPI does more than document an HTTP API. It gives tools a shared understanding of an interface. AsyncAPI does the same for event-driven systems. GraphQL SDL describes GraphQL schemas. Protocol Buffers describe RPC interfaces. More recently, mcpdesc has taken a similar approach for MCP servers by providing a static description that tooling can consume independently of a running server.
These specifications are valuable because they establish shared semantics. Documentation generators, validators, catalogs, CI pipelines and governance tools can all interpret the same description. API products do not have an equivalent foundation. A payment product may combine an HTTP API for initiating payments, an event-driven API for status updates and another interface for managing mandates. Documentation, SDKs, workflows and examples belong to the same product. Yet there is no common, machine-readable way to describe that product itself.
Instead, every API management platform, developer portal or internal catalog builds its own interpretation.
The missing layer is semantic
At first glance, this looks like a portability problem. It is not. Portability is only one consequence of something more fundamental: there is no shared description of what an API product actually is.
Today, API management platforms provide concepts for grouping and publishing APIs. Depending on the platform, these concepts also include subscriptions, quotas, policies, approvals and portal publication. Those capabilities are valuable. The difficulty is that the platform-specific model often becomes the only machine-readable representation of the product.
Every other tool like catalogs, portals, governance pipelines, documentation generators or release automation must either understand that proprietary model or create its own.
Doesn’t APIs.json already solve this?
APIs.json is the most important counterexample and any proposal in this area should start there. It already provides a machine-readable index of APIs together with contracts, documentation, SDKs, workflows and many other related assets. The open question is whether discovery and product semantics are the same thing.
A discovery document can identify related APIs and resources. A product description would additionally express that these interfaces and resources together constitute one versioned product. That relationship becomes explicit and machine-verifiable. This may turn out to be a distinction without a meaningful difference. If a constrained APIs.json profile can express the same semantics, another specification would add little value.
Data product specifications point in a similar direction. They separate the identity of a product from the interfaces and assets associated with it. Their scope is much broader than what would be required here, but the architectural separation is instructive.
A foundation, not another platform
The purpose of such a specification would not be to replace API management platforms. Nor would it attempt to describe pricing, subscriptions, quotas, deployment stages, runtime policies or operational behaviour. Those belong to runtime platforms. The missing foundation is considerably smaller.
It should answer only a handful of questions.
What is the API product?
Which APIs belong to it?
Which supporting resources belong to it?
Which version of the product does this describe?
Conceptually, the document could be as small as:
oaps: 0.1.0
info:
...
apis:
...
resources:
...
The referenced APIs would remain described by OpenAPI, AsyncAPI, GraphQL SDL or Protocol Buffers. Documentation, workflows, SDKs and examples would remain in their own formats. The product description would simply establish that these artifacts belong together.
Why this matters
Once an API product has a common machine-readable description, different kinds of tooling can build upon it without inventing their own interpretation. A catalog can expose the product. A release pipeline can validate the referenced contracts. Documentation tooling can assemble the associated assets. Governance tooling can evaluate product-level rules. An API management adapter can generate the platform-specific configuration required by IBM API Connect, Apigee, Azure API Management, Kong or Gravitee. Platform-specific models do not disappear. They simply stop being the foundation on which every other tool depends.
The real question
The first discussion should not be about YAML fields. Nor should it be about extension mechanisms. The real question is whether API products represent a distinct semantic concept that deserves a shared machine-readable description.
If the answer is yes, several follow-up questions become interesting.
Is this fundamentally different from API discovery?
Could APIs.json express the same semantics?
What is the smallest useful core?
Which responsibilities belong in the foundation, and which should remain platform-specific?
Only after those questions have convincing answers does it make sense to design a schema. An API product may need the same thing that OpenAPI and, more recently, mcpdesc provide for their respective domains: a shared, machine-readable foundation that different tools can understand without first agreeing on a particular implementation.
That is the hypothesis worth validating.