api-designlisted

# API design An API is a promise you keep for years. Design for the caller you cannot see, then keep the promise boring. ## Method 1. **Start from the caller's sentence.** Write the code or request the caller *wants* to make, before any implementation exists: `POST /notebooks/{id}/share` or `client.notebooks.share(id)`. If the ideal call is awkward to say, the design is wrong at the root. 2. **Name by domain, shape by convention.** Nouns for resources, verbs for actions that are not CRUD. Same word for the same concept everywhere , an API where "document", "file", and "source" mean one thing teaches distrust of every name. 3. **Make the common case one call** with obvious defaults, and the rare case possible with explicit options. Never make every caller pay a configuration tax for flexibility one caller needs. 4. **Errors are API.** Every failure a caller can cause gets a distinct, documented, stable error with: what went wrong, on which input, and what to do. A caller should distinguish "you sent garbage" (4xx / typed error), "we broke" (5xx), and "try later" without parsing prose. 5. **Design for the invalid states not to exist.** Required pairs travel in one object; mutually exclusive options are one enum, not three booleans; ids that must belong together are validated together. If misuse compiles or returns 200, it will ship. 6. **Version from day one, break never.** Additive change is free (new optional field, new endpoin