API design

Contracts, compatibility, error semantics, versioning, and interface design.

Entries (5)

API contracts and compatibilityDefine the promise an API makes to its clients, and change it without breaking the code that already depends on it.

API versioning and evolutionChange a published API over time without a coordinated flag day, and choose versioning only when compatible evolution cannot carry the change.

Error modeling and error normalizationReport failures so a client can tell them apart and act on them, and give every layer a consistent error shape.

Pagination and bounded collection readsReturn a collection in bounded pages with stable ordering, so a read cannot grow without limit as the data grows.

Resource and operation designDecide what an API exposes as things and what it exposes as actions, and give each operation clear and predictable semantics.