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, noting any intentional deviations. EDITABLE VARIABLES: • [APPLICATION_FEATURE] — what the API exposes (e.g. "user management for a SaaS product", "payment processing") • [CONSUMERS] — who will call this API (internal services, mobile apps, third-party developers) • [AUTH_METHOD] — preferred authentication mechanism • [SCALE_EXPECTATION] — approximate request volume to inform rate limiting decisions OUTPUT FORMAT: **Base URL:** /api/v[N]/ **Authentication:** [Mechanism + example header] **Rate Limiting:** [Strategy + headers] **Endpoints:** [For each resource group] GET /resource — [description] Request: [params/body schema] Response 200: [schema] Response 400/404/401: [schema] **Error Response Standard:** [Consistent error envelope format] **Versioning & Deprecation Policy:** [Strategy] **[TRADEOFF:] notes** [Design decisions explained] QUALITY BAR: A developer who has never spoken to you should be able to build a complete client integration using only this API design document, without asking a single clarifying question.