Which REST API design decisions are expensive to change once consumers exist?

What is being tested

Whether you know which choices become permanent the moment a third party integrates.

The expensive ones

1. Pagination on collections. Retrofitting it is a breaking change, and without it an endpoint that is fine against the median object falls over on the outlier — the repository with 300,000 issues, the organisation with 50,000 members. Add it in version one, with a maximum page size, or a client will request everything and call it pagination.

2. Identifier scheme. Sequential identifiers let an attacker walk the dataset once they find one authorisation gap, and they leak business volume. Changing them later breaks every stored reference.

3. The error model. Clients build logic on error codes, so a changed code string breaks them. Machine-readable codes, stable, documented, with the field concerned and whether the error is retryable.

4. Field exposure. Serialising whole objects means a new sensitive column silently appears in every response that uses that serialiser. Explicit field selection prevents an entire class of accidental disclosure.

5. Whether responses are cacheable, and on what key — including whether anything user-specific can appear, which is the highest-severity caching mistake available.

The discipline that keeps it evolvable

Additive change only: new fields optional, unknown fields ignored, nothing removed or retyped, enums extended carefully because strict parsers reject unknown values.

Enforced mechanically — schema compatibility checks in CI — not by convention, which fails within a year.

The prerequisite for ever removing anything

Per-consumer, per-field usage instrumentation, collected over a window long enough to catch monthly and quarterly jobs — which are exactly the integrations whose breakage is most damaging.

It cannot be added retroactively to history, which is why it belongs in version one alongside the pagination.