Skip to content

CONCEPT Cited by 1 source

API-first principle

Definition

API-first is the discipline of defining a service's external API contract (typically as an OpenAPI / Swagger document) before writing the implementation, then using the contract — not the implementation — as the source of truth for: client SDKs, server stubs, documentation, tests, and compliance checks. It inverts the default "code-first" flow where the API emerges as a by-product of implementation.

The principle is only operationally meaningful when paired with build-gate enforcement — a linter (e.g. Zally) that runs on every PR/build and fails the pipeline on MUST-severity contract-guideline violations. Without the gate, "API-first" collapses to "we have a doc somewhere."

The Zalando instantiation

Zalando operationalises API-first with three components (Source: sources/2021-06-30-zalando-how-we-use-kotlin-for-backend-services):

  1. Published RESTful API Guidelines — opensource.zalando.com/restful-api-guidelines as a living open-source document, rules tiered by severity (MUST / SHOULD / MAY / HINT).
  2. A linter that codifies the guidelines — Zally runs on OpenAPI specs as the executable embodiment of the written document.
  3. CI-level MUST gating — teams configure CI so Zally MUST-violations fail the build, making the guideline contractually binding rather than aspirational: "API linting can also be required to pass for MUST validations on every build."

A central API portal lists all Zalando APIs with their Zally results attached — the catalog and quality-gate dashboard combined.

What distinguishes API-first from schema-first

  • API-first scopes to public-surface contracts (the externally-exposed REST / gRPC / GraphQL API of a service), not storage schemas. See concepts/schema-as-code for the database analogue.
  • API-first is usually paired with contract-derived codegen — server stubs, client SDKs, docs all generated from the spec; implementation teams fill in stub bodies rather than designing method signatures.
  • API-first enables API reviews independent of code reviews — architects/tech-leads/platform teams can review the OpenAPI spec before any implementation work, catching breaking-change or guideline-violation risks before teams have sunk weeks into a specific shape.

Trade-offs

  • Upfront cost — designing the contract properly takes more time than typing the first handler. The cost is amortised over every client integration afterwards.
  • Spec-code drift risk — without generation discipline, the OpenAPI spec and the running service's actual behaviour can diverge. Codegen on the server side (stubs) is the main mitigation.
  • Not a fit for rapid-iteration internal APIs — the overhead makes sense for cross-team, cross-service, or external-facing APIs; less so for a two-service internal integration behind one team's control.

Seen in

Last updated · 476 distilled / 1,218 read