← Back to principles

API

One Definition, Zero Drift

What this means in practice

Define the API contract once, in a schema that is treated as the single source of truth. That schema must drive the specification, validation, and generated types so that what teams design is exactly what runs in production. The contract is enforced at both design time (through type checking) and runtime (through validation and serialisation). Undocumented behaviour is treated as a defect.

Why this matters

When the contract is defined in one place and enforced end-to-end, teams avoid drift between documentation and implementation. It enables parallel delivery by letting consumers build against a stable spec, and it reduces incidents caused by ambiguous or inconsistent behaviour. Strong contracts also speed up change by making breaking differences explicit and by providing confidence that the API will behave as described.

Practices that meet this principle

  • Adopt schema-first development (for example: Zod, TypeBox)

  • Generate TypeScript types from the schema, and use them throughout implementation

  • Generate OpenAPI contracts from schemas

  • Hand-written OpenAPI contracts for maximum control, with tooling that prevents drift from the schema and implementation

  • Enforce the contract at runtime with schema-based validation and serialisation (for example: Fastify schema serialisation and deserialisation)

Validation

A project meets this principle when:

  • Validation performed at runtime to ensure the runtime matches the contract

  • Types, validation, and spec are generated or derived from the same schema

  • The published specification matches production behaviour

  • Runtime validation rejects invalid inputs and prevents invalid outputs

  • Undocumented behaviour is detected and removed (or formalised into the contract)