Designing APIs teams can live with
An API is a promise. Once another team depends on it, every shortcut you took becomes their problem too. The useful question early on is not which framework, but what exactly am I guaranteeing and for how long.
Start with the resource vocabulary. If the names in your endpoints do not match the names the business uses, every future conversation costs translation. Write the nouns down before writing the routes.
Version at the boundary, not in the code. Additive changes should never require a version bump; breaking ones always should. Document the difference explicitly so consumers know which changes can land without their involvement.
Finally, ship the documentation with the endpoint. A Swagger definition written a sprint later is fiction. Written alongside the handler, it is a test of whether the contract actually makes sense.
- API Design
- Node.js
- System Architecture
- PostgreSQL