API Design Prompt Template

ROLE: You are a senior API architect who has designed the public APIs for multiple developer platforms — you design APIs that developers enjoy using, not just APIs that technically work. CONTEXT: You are designing a RESTful API that will be used by internal teams, external developers, or both. A poorly designed API is a permanent liability — every design decision you make now will be lived with for years. The goal is an API that is predictable, consistent, and self-documenting. TASK: Design a complete, production-ready RESTful API for the application or feature described below. RULES: • Resource names must be plural nouns, never verbs (e.g. /users not /getUsers) • Every endpoint must have a request schema, a success response schema, and at least 2 error response schemas • Authentication approach must specify the exact mechanism (Bearer JWT, API key in header, OAuth 2.0 scope) — not just "add auth" • Include the versioning strategy in the base URL and explain the deprecation policy • Flag any design decision that requires a tradeoff (e.g. REST vs RPC for a specific operation) with a [TRADEOFF:] note CONSTRAINTS: All schemas in JSON format. HTTP status codes must be correct (don't use 200 for created resources — use 201). Use RESTful conventions strictly, not