Contracts agreed before either side writes code.

The API was finished.
The integration was not.

OpenAPI or GraphQL schema agreed first, generating server validation, client SDKs and docs, so drift between them becomes impossible rather than likely.

Keys on every mutating operation, defined retry behaviour, and tests that replay requests to prove exactly one effect occurs.

Versioning strategy, consumer tracking per API key, and a written support window so a sunset is a process rather than an argument.

OAuth or key-based auth with granular scopes, per-consumer quotas, and limits that return useful headers rather than a bare 429.

Generated reference docs, a sandbox with seeded data, self-serve keys and copy-paste examples in the languages your partners actually use.

Signed payloads, at-least-once delivery, exponential backoff, a replay endpoint and a delivery log consumers can inspect themselves.

Where adoption depends on a developer succeeding alone at midnight without contacting your team.

Shared services several squads build on, where a breaking change becomes four teams’ sprint planning.

Middleware between systems that were never designed to talk — usually including one with no documentation and one owner who left.

Where old app versions persist for months and the API has to tolerate every build still in the wild.

Outbound events partners rely on, where a silent delivery failure damages trust more than an outage.

Putting a clean, documented contract in front of something old, so new work stops inheriting its shape.

The half of API workthat is pure repetition.

Handlers, types and SDKs

Server handlers, validation, client libraries and typed models generated from the contract in every language your consumers use. Hand-writing four SDKs is weeks of work with no thinking in it.

Every status code, every path

Integration tests generated across success, validation failure, auth failure, rate limit and timeout for every endpoint. Previously the coverage that got trimmed when the sprint tightened.

Reading the undocumented system

Existing code, database schemas and network traces read to work out what an undocumented service actually does. This is normally the single largest unknown in an integration estimate.

Contracts and failure semantics stay hand-designed.

What the resource model should be, how a partial failure behaves and what a deprecation window commits you to are consequential decisions made by senior engineers. Efficiency on the surrounding volume is what makes room for that thinking.

When an API
is not the answer

A public-shaped API for a single internal caller adds a boundary, a version and a document for no benefit. A library or direct call is simpler.

Partner APIs built speculatively get no adoption and still need maintaining. Wait for the second real request.

An API freezes your model in a contract other people depend on. Publishing before the model is stable means breaking changes immediately.

For nightly batch exchange, SFTP or your integration platform is cheaper and more robust than a bespoke API with a real-time promise.

Not the average. Consumers experience the tail, and it is the tail that breaks their timeouts.

Broken out per API key, so a single partner integrating badly is visible instead of being averaged away.

Delivered on first attempt versus after retry versus dead-lettered. Silent delivery failure erodes trust faster than downtime.

How often a replayed key is caught. Rising numbers indicate consumer retry storms worth investigating.

Traffic per version and per consumer, which is what makes a deprecation a plan rather than a hope.

How long a new consumer takes from key issuance to a working request. The clearest measure of developer experience.

What an API
connects to