API design

An API is a promise. Implementation is cheap to change; a published interface is not, because every caller has to move with you. Design it as though you cannot change it, because roughly speaking you cannot.

Design from the caller's side. Write the code that calls your API before you write the API. If that code is awkward, the design is wrong, and you have found out in two minutes instead of after three teams have integrated.

1. Model the domain, not the storage

The most common failure is exposing your database schema through HTTP. It couples every consumer to your internal structure, so a routine table split becomes everyone's migration.

Name resources and operations in the language your users use, not your tables. If a caller must understand your persistence model to use the API, the abstraction has already failed.

Done when: you could change the storage layer without touching the interface.