Invocation points:

Adding a new public API endpoint
Redesigning an internal API boundary between services
Code review of a PR that introduces HTTP handlers
A slice whose acceptance criteria include "the API works"
A GraphQL schema change

<core_principle> CALLERS OUTLIVE YOUR ASSUMPTIONS. An API you ship today has to keep working when your internals change, when the mobile app version two is still in use, and when a third party integrates against it. Design for extension, not just for the current caller.

HONEST STATUS CODES. 200 OK with {"error": "not found"} is a lie. 404 says not found. Use the HTTP semantics the protocol offers — HTTP clients, caches, and intermediaries rely on them.

api-design