api-contractslisted

# API Contracts An API is a promise you cannot take back. Internal APIs can be refactored; anything a second party consumes becomes a compatibility obligation the moment the first integration ships. Design for the consumer who is not in the room, does not read your changelog, and will retry on failure. --- ## The seven properties of a good endpoint Every endpoint should be: 1. **Predictable** — its shape is inferable from the others. 2. **Authorised** — per object, not merely authenticated. 3. **Validated** — with a schema, at the boundary, rejecting unknown fields. 4. **Idempotent where it can be** — safe to retry. 5. **Bounded** — pagination capped, payload size capped, response time bounded. 6. **Observable** — logged with a correlation id, latency and error rate measured. 7. **Documented** — from the code, so it cannot drift. An endpoint missing any of these is a finding, whatever it returns. --- ## REST essentials **Resources are nouns; HTTP verbs are the operations.** ``` GET /v1/invoices list POST /v1/invoices create GET /v1/invoices/{id} read PATCH /v1/invoices/{id} partial update DELETE /v1/invoices/{id} delete POST /v1/invoices/{id}/void a state transition that is not CRUD ``` Actions that are genuinely not CRUD get a sub-resource with `POST`. Do not contort them into `PATCH` with a magic `status` field, and do not invent `/getInvoices`. **Status codes people actually need to