Generate a comprehensive API design document with endpoints, data models, authentication, error handling, rate limiting, and OpenAPI spec — ready for engineering review.
You are a senior software architect. Generate a comprehensive API design document for the following project:- **Project name**: [project name] - **Description**: [what this API does] - **Tech stack**: [e.g., Node.js + Express + PostgreSQL / Python + FastAPI + MongoDB] - **Authentication**: [JWT / OAuth2 / API Key / Session-based] - **API style**: [REST / GraphQL / gRPC] - **Primary consumers**: [web app / mobile app / third-party integrations / internal services] ---
- High-level architecture diagram (describe in text)
- Base URL structure and versioning strategy
- Request/response format (JSON, content types)
- Pagination strategy (cursor vs offset, default page size)
- Filtering and sorting conventions
- HATEOAS or linking strategy (if applicable)For each core entity: - Entity name and description - Field definitions with types, constraints, defaults - Relationships (1:1, 1:N, N:M) - Indexes and unique constraints - Soft delete strategy - Audit fields (createdAt, updatedAt, createdBy) Define these entities: [entity 1, entity 2, entity 3, ...]
For each endpoint, provide:
- HTTP method + path
- Description
- Auth required (yes/no) + required role
- Request headers
- Path parameters + query parameters (with types and validation)
- Request body schema (with examples)
- Response schema (success + error, with examples)
- Status codes used
- Rate limit tier
Group endpoints by resource:
- CRUD for each entity
- Search/filter endpoints
- Bulk operations
- Aggregate/stats endpoints- Standard error response format
- Error code registry (map of code → message → HTTP status)
- Validation error format (field-level)
- Business logic error patterns
- Rate limit exceeded response
- Authentication/authorization error responses- Event types and payloads
- Webhook registration endpoint
- Retry policy and backoff strategy
- Signature verification
- Event ordering guarantees- Caching strategy (what to cache, TTLs, invalidation)
- Database query optimization notes
- Connection pooling configuration
- Horizontal scaling considerations
- CDN and static asset strategyGenerate a valid OpenAPI 3.0 YAML snippet for the top 5 most important endpoints, including:
- Schemas
- Security definitions
- Example requests and responses
---- Use tables for data model fields and endpoint summaries
- Include code blocks for request/response examples (JSON)
- Use consistent naming conventions (camelCase for JSON, kebab-case for URLs)
- Mark optional vs required fields clearly
- Total length: 2,000-4,000 wordsNo gallery images yet.