Insights · Modernization

API-first integration: contracts before platforms

REST/SOAPCDC

Key takeaway

The interface contract is the primary artifact: designed before the code, versioned like it, with docs and tests generated from it.

Most integration pain is not transport pain — it is expectation pain. A consumer assumed a field was mandatory; a producer renamed an enum; nobody owns the question. The fix predates the microservices era by decades: Fielding’s dissertation names the “uniform interface between components” as the central feature of REST, because generality of contract — not cleverness of implementation — is what lets “implementations … [decouple] from the services they provide, which encourages independent evolvability.” API-first is that principle run as a process: write the contract down, agree on it first, generate everything else from it.

What “API-first” actually commits you to

The artifact is standardized and boring by design. The OpenAPI Specification “defines a standard, programming language-agnostic interface description for HTTP APIs” — documentation, client and server code generation, and testing tools all consume it. For event-driven systems, AsyncAPI does the same job for asynchronous interfaces — “much like OpenAPI (aka Swagger) does for REST APIs” — covering the channels, message schemas and bindings that a Kafka-class event backbone runs on. Together they make one practice possible across both integration styles: the contract exists before the platform choice, not after.

Microsoft’s architecture guidance states the orientation plainly: “OpenAPI promotes a contract-first approach instead of an implementation-first approach.” Concretely, the workflow is:

  1. Design the contract with consumers. The negotiation happens on the document, where changes are cheap — not on the running service, where they are outages.
  2. Review it like code. Contracts live in version control; changes ride pull requests; compatibility is checked, not presumed.
  3. Generate the periphery. Docs, mocks, client SDKs and server stubs come from the definition. The design-first benefit is parallelism: testers and technical writers work from the agreed definition, and mock servers let consumers build “before the backend is ready.”
  4. Conform. CI compares the implementation against the contract on every change — drift fails the build.

The anti-pattern contracts replace

The thing API-first replaces is the integration database — “a database which acts as the data store for multiple applications.” Fowler’s diagnosis is exactly the coupling mechanism: the shared schema “has to unify what should be separate bounded contexts,” schema changes “have to be negotiated,” and the database becomes the coupling point between applications that now cannot evolve independently. Every estate that integration-databases ever built relearned the same lesson: a contract nobody can see is a contract nobody can rely on. The visible, versioned interface is not bureaucracy; it is the minimum viable diplomacy between teams.

Design conventions worth standardizing

A contract style guide turns individual API designs into an estate-wide vocabulary. Google’s API design guide is the public existence proof at ecosystem scale: resource-oriented design, standard methods (get/list/create/update/delete), naming conventions, versioning and backward-compatibility rules — conventions in production since 2014 across thousands of APIs. You do not need Google’s scale to need the answer; you need only two teams and one integration. The Azure design guidance covers the same ground for REST: nouns not verbs, correct status codes, idempotent methods, and a deliberate choice among the four versioning strategies (URI, query string, header, media type).

For events, the equivalent convention is: one schema per event type, registered and compatibility-checked (the schema-registry discipline from the backbone article), with AsyncAPI documents as the human-facing contract for each channel.

Govern the lifecycle, or the contracts rot

Contracts are promises, and promises age. Two research findings should shape your governance:

  • Deprecation is where contracts go to die. An empirical analysis of 2,224 OpenAPI specifications (Yasmin, Tian & Yang, 2020) found “severe deprecation-related problems in existing RESTful APIs” — providers keep old versions alive without processes, or break clients without notice. Versioning and deprecation need owners, timelines and machine-readable markers, or they happen by accident.
  • Contract quality is machine-checkable. RESTRuler (Bogner et al., ICSA 2024) demonstrated static analysis of OpenAPI descriptions against 14 design rules across 2,300+ public specs at 91% precision. Lint your contracts in CI the way you lint code: naming, pagination, error models, required documentation fields.

The practical governance loop: contract PR with compatibility check → generated-consumer contract tests in the provider’s pipeline → deprecation with a published sunset date → removal only when telemetry shows zero traffic. Each step is a check a machine can run, which is what keeps the human promises honest.

Where API-first sits in the architecture

API-first is the discipline that makes the rest of the estate’s patterns livable. Bounded contexts stay honest because their published contracts — not their tables — are the integration surface (the DDD article draws the contexts; the contracts police them). The modular monolith’s modules expose internal contracts that become the service interfaces on extraction day (the extraction path). The event backbone’s topics carry AsyncAPI-documented schemas. And platform teams publish golden paths where a new service scaffolds with contract linting, mock generation and conformance tests included — the integration discipline arrives built-in, not as a retrofit.

Contract-first, end to end

Sources