Your platform has 60 internal APIs. Teams repeatedly rebuild capabilities that already exist because they cannot find or understand them. What do you build?

The problem is discovery, then comprehension

Duplication is the symptom. Teams are not choosing to rebuild; they cannot find what exists, or cannot tell in reasonable time whether it fits.

So the measure to optimise is time from arriving to a first successful call — and it is set by the portal, not by the APIs themselves.

Build a developer portal

A searchable catalogue of every API with ownership, maturity, support level and status. Discovery first; nothing else matters if the API cannot be found.

Reference documentation generated from specifications, so it is always current. Hand-written reference docs drift and, once distrusted, are worse than none.

Guides and worked examples, because reference alone does not teach the sequence of calls that accomplishes a real task. This is the gap that generated documentation never fills and where the highest return is.

Self-service credentials and a sandbox, removing a human queue from the critical path.

Interactive try-it in the browser, plus generated client libraries for the platform's main languages.

Fix the production side too

Spec-first for new APIs: the contract is designed and reviewed by consumers before implementation, when changing it is free. It also unblocks parallel work — consumers generate clients and mocks immediately.

The cost is drift between spec and implementation. Control it with contract validation in CI asserting the implementation matches the spec, plus request/response validation at the gateway.

Code-first is acceptable for existing APIs — the spec always matches the code — but the contract then reflects internal models rather than a designed interface.

Require a spec in the catalogue as a release gate. Documentation that is optional is not written.

Governance that is worth having

A small set of enforced standards — error format, pagination style, authentication, versioning, naming — checked by a linter in CI rather than by a review board. Automated standards are followed; committee standards are resented and evaded.

Measure it

Track time-to-first-call, search queries returning nothing (a direct list of gaps in the catalogue), support questions per API (a direct list of documentation gaps), and reuse of existing APIs in new projects.

What a strong answer adds

Recognising that internal APIs are products with users. The same disciplines that make a public API adoptable — discovery, onboarding, documentation, support, deprecation policy — apply internally, and their absence is exactly why capabilities get rebuilt.