Make your systems talk to each other.

An API is the one part of a system you cannot quietly refactor, because other people's code depends on its exact shape. That makes a handful of early decisions unusually costly to get wrong — not because they are difficult, but because they are permanent.

The ones that matter most

• Versioning in the path from day one, even with only one version. Retrofitting it means breaking every consumer once, and that migration never happens at a convenient time.
• Opaque identifiers rather than sequential integers, never reused after deletion.
• Errors a client can act on: correct status code, stable machine-readable code that never changes meaning, human-readable message, and a pointer to the field at fault.
• Cursor pagination rather than offset, which silently skips or duplicates rows when records are inserted mid-traversal.
• UTC timestamps in one format, money as integer minor units with an explicit currency, and a documented distinction between null, absent and empty.

Built for the network you actually have

Publish rate limits and return remaining quota in headers so consumers can behave well. Accept an idempotency key on anything that creates or charges, because networks fail after the server has already acted and the client will retry. Webhooks need retries with backoff, ordering guarantees stated plainly, and a replay mechanism for when the consumer was down.

Documentation that cannot drift

Hand-written API documentation is wrong within a quarter. We generate it from the definition, publish the schema, and treat a mismatch between docs and behaviour as a bug rather than a chore.