The portal nobody visits

The developer portal is the vendors' favourite selling point. It is the visible part of the platform, the one shown in the steering committee, the one that prompts "we will have an API store like the big players".

Then you look at the traffic figures a year after go live: a few dozen visits a month, half of them coming from the platform team itself.

The metric that counts, and it is not traffic

The number of visits says nothing: a developer who comes three times because he cannot find what he needs is counted three times. The metric tracked by the API publishers whose whole business is being adopted is the time to first successful call, measured from landing on the API page through to the first 200 response received by the consumer.

It can be measured without complicated instrumentation: the subscription creation date and the date of that consumer's first authenticated call are both in your logs. The distribution of that gap, API by API, is the only portal dashboard that serves any purpose.

What it says is brutal. When getting a key goes through a ticket, the gap is counted in days and the median never comes down. When it is self-service, it is counted in minutes, and the APIs whose gap stays long are exactly those whose documentation is a raw OpenAPI contract.

The poor man's version of the same measurement fits in one question put to a developer on a consuming team: how did you integrate the last internal API you use? If the answer is "I asked someone who knew, on Teams", the portal is not the fastest route, and that is the only criterion that counts.

The catalogue is unreadable because it is indexed on the wrong text

A developer does not browse a catalogue, he searches it for a word. And the word he types is the one from his business: "transfer", "beneficiary", "delivery point".

But a catalogue auto-generated from the gateway indexes what the contract contains: paths, operation identifiers, schema names, often in English and often abbreviated. The consumer's vocabulary appears nowhere in it. The search returns nothing, the developer concludes the API does not exist, and he rebuilds it.

That is why the plain language description is not an editorial courtesy: it is the only text the search can work on. A useful page names the business domain, the synonyms used internally, and the system the data comes from, which is often the only term the requester knows.

The rule that decides everything: one door only

Portals that stay alive have one thing in common, and it is not technical: there is no other way to obtain access. No key handed out by the platform team in a direct message, no exception for a project in a hurry, no service account created by hand to unblock someone.

Every exemption is a shortcut that becomes the norm. As long as getting a key another way takes less effort, teams pass the existing keys around under the table, and security rests on shared credentials nobody will know how to revoke.

Two conditions make that rule sustainable, and they have to be set before it.

An owner, whose job it is to keep the catalogue alive, to review the documentation and to turn down a substandard publication. Without that role, the portal becomes a dumping ground for OpenAPI contracts.

And an enforceable publication standard, which does not accept an API without a plain language description, call examples and a team contact. It is a governance rule that automates very well at publication time.

An internal portal is not a public portal

The most frequent design mistake is to borrow the conventions of a public portal, which are those of a sales site: a home page, selling points, a sign-up journey.

The internal consumer has nothing to buy and does not need to be convinced. He needs three pieces of information that public portals never carry, because they would make no sense outside: which team owns this API and where you talk to them, what its real service commitment is, and whether it is allowed to be called from the context you are in. The last one is the one that is missing most: a developer who does not know whether an internal API is open to his domain will open a ticket, and we are back to the delay.

Conversely, everything that belongs to commercial promotion, to handing out brochures and to the anonymous trial journey is wasted work internally.

What really fails

The portal is the least technical component of the platform, and that is exactly why it fails most often: nobody feels responsible for a problem that is not technical. A platform team knows how to diagnose latency, it has neither the mandate nor the instinct to refuse mediocre documentation.

It is an organisational decision, not a tooling one, and it gets made before the product is bought rather than a year after go live.