Common API¶

Interface (shared API) — instantiates Interoperability Standardization

A single published interface — a fixed set of operations with defined inputs, outputs, and errors — that many systems implement or call, so each integrates once against the shared surface instead of pairwise with every other.

A Common API is a shared, published interface: a named set of operations, each with defined inputs, outputs, error responses, and permission rules, that any number of systems can implement on one side and call on the other. Its distinguishing move is to standardize the callable surface — the verbs one system offers another (get-balance, initiate-payment) — while leaving each participant's internals entirely private. Where a data schema fixes the shape of a record and a protocol fixes the choreography of messages, the API fixes what operations exist and what each promises, so a caller writes to the interface once and works with every provider that offers it. It is the reusable integration socket that turns "integrate with each partner" into "integrate with the standard."

Example¶

A fintech app wants to show a user their balances and initiate payments across nine banks. Without a shared interface it would build nine bespoke integrations, each reverse-engineered from a different bank's private systems and each breaking on its own schedule. Under an Open Banking / PSD2-style regime the banks instead expose a common API: the same accounts and payment-initiation operations, the same request and response fields, the same authorization flow and error codes, regardless of the bank behind it.

Now the app implements against that one interface and, in principle, reaches all nine banks — and a tenth that later exposes the same API needs zero new integration code. Each bank keeps its own core banking system entirely private; all that is standardized is the boundary they present. A caller receives a 403 for an unconsented account from every bank in the same shape, so error handling is written once. The outcome: a new market entrant integrates in weeks, not a year of pairwise deals.

How it works¶

The API is defined as an interface contract independent of any implementation: the operation set, each operation's request and response structure, its error taxonomy, authentication and permission requirements, idempotency and pagination rules, and rate expectations. Providers implement it behind their own systems; consumers code against the published definition. Its leverage is the scope decision — drawing the line between what the interface exposes (and therefore standardizes) and what stays internal — plus the contract that lets either side re-engineer its internals freely as long as the boundary promises hold. The definition is often machine-readable (an OpenAPI/gRPC description) so client stubs and mock servers can be generated straight from it.

Tuning parameters¶

Surface breadth — how many operations the API covers. A wide surface enables more without custom work but is harder to implement fully and evolve; a narrow one is easy to adopt but leaves gaps to bespoke integration.
Granularity — coarse operations (few, do-a-lot calls) vs. fine (many small ones). Coarse is simple but rigid; fine is flexible but chatty and easy to misuse.
Contract strictness — how tightly inputs, outputs, and error shapes are pinned. Tight contracts guarantee uniform behaviour; loose ones tolerate provider variation but re-open incompatibility.
Permission granularity — how finely access and consent are scoped in the contract, trading safety against integration friction.
Versioning stance — whether the interface promises stability or fast iteration; this hands off to Version Negotiation Scheme at runtime.

When it helps, and when it misleads¶

A common API is the right instrument when many systems must invoke one another's capabilities, not merely swap files — payments, identity, cloud services, platform ecosystems. Its central payoff is combinatorial: it turns an N-by-N mesh of bespoke integrations into N implementations of one interface, so each new participant adds linear, not quadratic, integration cost.^[1]

It misleads when the standardized surface leaks the internals it was meant to hide — an API that mirrors one provider's private data model forces everyone else to emulate that model, recreating the coupling it promised to remove. Too narrow, and consumers fall back to bespoke side-channels for what the API omits, fragmenting the very interoperability it created. And a common signature is not common meaning: two providers can implement the same get-balance and disagree on whether "balance" includes pending transactions. The discipline is to scope the interface around the shared cross-system function rather than any one implementation, and to pair it with a shared vocabulary for the terms its fields carry.

How it implements the components¶

interaction_surface_scope — the API is the drawn boundary: it defines exactly which operations, objects, and transactions are standardized and which internals stay local to each participant.
interface_contract — it states what each caller may assume at the boundary — inputs, outputs, error behaviour, permissions, obligations — so providers can change internally while preserving those promises.

It does not fix the on-the-wire message sequence, timing, or handshake — that is Protocol Specification — nor the internal structure of the data objects it passes, which is Data Schema.

Instantiates: Interoperability Standardization — it is the reusable interaction surface many participants implement or consume.
Consumes: Data Schema supplies the structure of the objects the API's operations carry.
Sibling mechanisms: Protocol Specification · Data Schema · Technical Standard Specification · Semantic Glossary · Conformance Test Suite · Reference Implementation · Certification Program · Interoperability Trial · Standards Body · Version Negotiation Scheme · Interagency Interoperability Agreement

References¶

[1] Connecting N systems pairwise takes on the order of N² bespoke integrations; a shared interface every system implements or calls reduces that to N. This move from quadratic to linear integration cost is the core economic argument for standardizing an interaction surface rather than negotiating each connection. ↩