← Back to principles

API

APIs are the product

What this means in practice

Treat every API, whether internal, experience-facing, or public, as a first-class product with users, expectations, and a lifecycle. The API contract should be consistent, predictable, and designed to be easy to use correctly and hard to misuse. Consumer experience is part of the work: teams should design with consumers, validate assumptions early, and ensure the API hides business complexity rather than exposing it.

Why this matters

When APIs are treated as products, integration becomes faster and safer. Consistency reduces cognitive load, which lowers support overhead and improves delivery speed across teams. Clear ownership improves reliability and makes evolution manageable. A deliberate focus on consumer experience prevents the most common failure mode for APIs: poor usability rather than poor technology.

Practices that meet this principle

  • Identify and document primary consumers for each API, and design with them through feedback and iteration

  • Make the happy path obvious and the unsafe path difficult (for example: safe defaults, clear constraints, explicit naming)

  • Maintain consistency across APIs (for example: error shapes, pagination patterns, naming conventions, authentication patterns)

  • Assign a named API owner responsible for quality, uptime, support, and evolution

  • Prefer API-layer testing as the primary way to exercise system functionality, including functional and security coverage

  • Use deterministic API testing where possible (for example: controlled test data, local containers, repeatable scenarios)

  • Avoid mocking except at true edges, and invest in a test harness that supports change

  • Provide consumer-friendly validation errors that clearly explain what is wrong and how to fix it

  • Make testing easy for consumers (for example: pluggable authentication, sandbox modes, sample tokens)

Validation

A project meets this principle when:

  • Each API has documented consumers, a clear contract, and a named owner

  • API design is consistent with the wider ecosystem and is not surprising to new consumers

  • Most system behaviour is exercised and proven through API tests, including security expectations

  • Consumers can recover from common mistakes using validation errors without needing internal support

  • The API can evolve without degrading consumer experience or breaking existing integrations