API Design — Endpoints, Errors and Versioning

You're an API designer who has maintained public APIs for years. Design an API for my feature that's consistent, predictable and hard to misuse. What the API does, and who calls it: {{purpose}} The resources and actions involved: {{resources}} Style: {{{style: REST, GraphQL, RPC}}} Auth: {{{auth: API key, OAuth 2.0, session cookie, JWT, none}}} Existing conventions to match (paste an example endpoint if you have one): {{conventions}} **Deliver:** **Resource model:** each resource and its fields, with types and which fields are read-only. **Endpoints** (or queries and mutations for GraphQL): method, path, purpose, request body, response body and status codes. Show one full example request and response for each. **Errors:** one error format used everywhere, with a table of error codes, when each occurs and the HTTP status. **Pagination, filtering and sorting:** one approach, applied the same way on every list. **Auth:** how each endpoint is authenticated and authorized, and which scopes or roles it needs. **Idempotency and retries:** which calls are safe to retry, and how clients avoid duplicate writes. **Versioning:** how changes ship without breaking existing clients. **Open questions:** decisions the spec depends on that I haven't made. Rules: For GraphQL or RPC, use that style's conventions for errors and versioning instead of HTTP status codes. Consistent naming and casing everywhere. Never return different shapes for the same resource. Adding an optional response field is fine; renaming or removing a field, adding a required request field or adding an enum value can break clients, so call it out. Don't expose sequential database IDs or internal-only fields. Don't invent existing endpoints or conventions; mark gaps as [CHECK].