Discovery

Discovery covers what lets a developer find an API, understand what it does and make a first successful call without asking anyone. The pillar is measured by a single indicator, the time between a developer arriving and their first successful call, and it determines the value of everything else: an API nobody can find is called by nobody.

Four elements

The catalogue. The list of what exists, with the owner and the lifecycle state. An API in deprecation has to say so before a new consumer adopts it.

The contract. An OpenAPI description, or AsyncAPI for event-driven APIs, that reflects actual behaviour. An inaccurate contract costs more than a missing one: the error is found at integration instead of on reading.

The try-it environment. A test token obtained with no paperwork, demonstration data, a call that runs from the documentation. Without it, the developer integrates blind and the gaps surface in acceptance testing.

Ownership. Who owns the API, who answers questions, where to report a problem. It is the most requested piece of information and the least often published.

The catalogue is generated, or it lies

A catalogue filled in by hand diverges from reality within a few months. The only version that lasts is generated from the source of truth: the contract lives in the service repository, publishing to the catalogue is a step in the integration pipeline, the catalogue reflects what is deployed. That pipeline is described in industrialise.

Generating the catalogue from traffic observed on the gateway is the symmetrical mistake: you get the list of what is called, not of what is offered. The two lists differ, and the gap between them is itself a piece of governance information.

Describing is not documenting

An OpenAPI contract gives the paths, the types and the return codes. Three things are almost always missing, and they are the ones integrators are looking for:

• a complete example call, with realistic values, copyable as is.
• the semantics of errors: what a 409 means on that specific operation, and what the caller should do.
• the usage limits: quotas, pagination, maximum sizes.

Their place is in the contract itself, as descriptions and examples, not in a separate page that will drift.

Time to first successful call

The indicator aggregates everything that actually gets in the way: contract quality, getting credentials, sandbox availability. It is hard to improve artificially, which makes it a sound basis for a target.

Beyond a day, the cause is no longer a tooling matter: it is a human approval chain, and it is handled as such.

Search

At a few dozen APIs, browsing by domain stops working: the developer is looking for a need, not an org chart. Search has to cover the content of the contracts, fields and descriptions included. Searching for IBAN has to return the APIs that handle one, even if none carries that word in its title. Many portals index the title and the description of the API, not the content of the contract. The point deserves a check during a demo, with real contracts loaded.