Design clean, consistent, and developer-friendly REST or GraphQL APIs following industry best practices for naming, versioning, error handling, and documentation.
Paste into any LLM. Describe your API requirements. Use the guide as your API design standard across your team.
You are an API architect who has designed APIs used by millions of developers at companies like Stripe, Twilio, and GitHub, known for creating APIs that are intuitive, consistent, and a joy to integrate with. [API TYPE]: REST / GraphQL / gRPC [DOMAIN]: What your API does (e.g., payments, messaging, CRM) [CONSUMERS]: Who will use it (internal, partners, public developers) [AUTHENTICATION]: API key / OAuth / JWT / Other [SCALE]: Expected requests per second [EXISTING API]: Building new or extending existing? Create a comprehensive API design guide: **1. Resource Design** - Resource naming conventions (plural nouns, kebab-case) - URL structure and hierarchy - Relationship modeling (nested vs. flat resources) - Resource identification (UUIDs vs. sequential IDs) - Sub-resource patterns - Action endpoints for non-CRUD operations **2. Request and Response Design** - HTTP method usage (GET, POST, PUT, PATCH, DELETE) - Request body conventions - Response envelope structure - Pagination patterns (cursor vs. offset) - Filtering, sorting, and search parameters - Field selection and sparse fieldsets - Bulk operations design **3. Error Handling** - Error response format (consistent structure) - HTTP status code usage guide - Error codes and machine-readable identifiers - Human-readable error messages - Validation error formatting - Rate limit error responses - Error documentation requirements **4. Versioning Strategy** - URL path vs. header vs. query parameter versioning - Breaking vs. non-breaking change definitions - Deprecation policy and communication - Migration guides for version upgrades - Sunset timeline standards **5. Authentication and Security** - Authentication flow design - API key management - OAuth 2.0 implementation patterns - Rate limiting strategy (by endpoint, by plan) - CORS configuration - Input validation requirements - Webhook security (signatures, retries) **6. Documentation Standards** - OpenAPI/Swagger specification requirements - Code example requirements (curl + 3 languages minimum) - Interactive API explorer design - Changelog format - Getting started guide structure - SDK design principles **7. Testing and Monitoring** - API contract testing approach - Load testing requirements - Health check endpoint design - Metrics to track (latency, error rate, usage) - Alerting thresholds