Designing stable APIs: contract first, consistent errors, add instead of change

Principles for interfaces that last: Hyrum's law, a single version, contract first, uniform errors, validation at the boundaries, additive changes, predictable names. Patterns for REST and types.

MethodologymetodologiaAPIarchitetturaingegneria del software19 November 2026 · 3 min read

An API is a promise. As soon as somebody uses it, that promise is costly to change. Designing a stable interface means deciding carefully what you promise and what you leave free.

Two laws to keep in mind

Hyrum's law. With enough users, every observable behaviour of the system will end up being used by somebody, even if undocumented. A random ordering of elements that "always works the same way" will become a dependency. Consequence: what you do not want to maintain, do not let leak.

The one-version rule. Avoid forcing customers to choose between different versions of the same thing. Where you can, the system has one current version, and changes are made in a compatible way.

Five principles

1. Contract first. You define the interface first (fields, types, errors, examples), then you build it. Whoever uses the API can start working on the contract before the code exists, and the discussions happen when they cost little.

2. Errors with consistent semantics. Every error has the same shape across the whole API: a stable code, an understandable message, and where needed the field involved. An API in which every entry point reports errors in its own way is hard to use.

3. Validate at the boundaries. You check inputs where they enter the system, not in every internal function. Inside, you can trust data that has already been validated.

4. Prefer adding to changing. Adding an optional field breaks nobody; changing its meaning or removing it does. Incompatible changes are to be treated as an event with advance notice.

5. Predictable names. The same words for the same things, the same style everywhere. Whoever has learned one entry point should be able to guess the others.

Patterns for REST APIs

  • Resources. You model nouns (orders, customers), not verbs; the actions are the protocol's methods.
  • Pagination. Every list can grow: you plan for it from the start, with a cursor or an index.
  • Filters. Explicit, documented parameters with reasonable defaults.
  • Partial updates. A partial update changes only the fields sent and does not reset the others.

Patterns for types

  • Discriminated unions for variants: a field that says which type it is, and the fields that exist only for that type.
  • Separation of input and output. What the client sends is not the same as what it receives (the identifier is assigned by the system).
  • Distinct types for identifiers. A customer identifier must not be passable where an order one is needed.

Warning signs

  • The interface defined after the fact, by describing the code.
  • Errors with different shapes in different places.
  • Validations scattered through the logic instead of at the boundaries.
  • Fields removed or renamed without notice.
  • Undocumented behaviours that customers already rely on.
  • Lists with no pagination.

An example

An API returns the amount as a number and one day you want to accompany it with the currency. Changing the field's type breaks the clients. Adding a new "currency" field next to "amount" breaks nobody; the eventual retirement of the old format is announced with a transition period.

When to use it

When designing APIs, boundaries between modules or any public interface; when creating REST or GraphQL entry points; when defining type contracts between modules or between frontend and backend.

This method derives from the open-source agent-skills family by Addy Osmani (MIT licence), rewritten and adapted.

This article is an OIAR skill

What you have just read is the content of a skill from the OIAR catalogue, written for people. Knowledge like this, but richer and deeper, written for the agents, drives the interviews, the analysis and the report inside the platform. Skills are used in OIAR: to try this one on a project of yours you need an account.

api-and-interface-designA method for designing stable APIs and interfaces: contract first, consistent errors, validation at the boundaries, additive changes, predictable names, REST patterns (resources, pagination, filters, PATCH) and type patterns (discriminated unions, separate input and output, distinct identifiers). Use it when designing APIs or boundaries between modules.