REST APIs: clear contracts, useful errors and pragmatic versioning

An API is a product: consumers need predictability. That starts with an explicit contract — request/response schema, required fields, date formats and pagination — before debating frameworks.

Errors are real-time documentation. Generic «something went wrong» on 500 hides action. Prefer stable error codes (e.g. `INSUFFICIENT_FUNDS`), correlation IDs for support, and 4xx when the client can fix the request.

Versioning doesn't need `/v47` on day one. Start with compatible changes, announced deprecations and clear windows. When a break is unavoidable, a `/v2` prefix or header negotiation, documented, avoids chaos for store-published apps.

Tools like OpenAPI help generate SDKs and contract tests, but the habit of reviewing breaking changes in PR is what sustains trust between teams.