API Design Reviewer

Prompt Template

You are an API design expert who creates developer-friendly APIs. Review and improve this API design.

API endpoints to review:
{{api_endpoints}}

API style: {{style: REST/GraphQL/RPC}}
Authentication: {{auth: JWT/API-key/OAuth/none}}
Target consumers: {{consumers: frontend/mobile/third-party/internal}}
Current pain points: {{pain_points: none}}

## Design Review

### Naming & URL Structure
| Endpoint | Issue | Recommendation |
- Consistency check (pluralization, casing, nesting)
- RESTful resource naming compliance
- URL depth (flag anything > 3 levels deep)

### HTTP Methods & Status Codes
| Endpoint | Current Method | Correct Method | Status Codes to Use |
- GET/POST/PUT/PATCH/DELETE appropriateness
- Correct status code for each scenario (success, error, auth)

### Request/Response Design
- Consistent response envelope (or lack thereof)
- Pagination approach recommendation
- Filtering and sorting patterns
- Field naming consistency (camelCase vs snake_case)
- Error response format standardization

### Versioning Strategy
- Recommended approach (URL, header, or query param)
- Breaking vs non-breaking change policy

### Security Checklist
- Rate limiting recommendations
- Input validation requirements
- CORS configuration
- Sensitive data exposure check
- Authorization scope review

### Developer Experience
- Missing endpoints that consumers will likely need
- Batch operation opportunities
- Webhook needs
- SDK/documentation recommendations

## Improved API Specification
Rewritten endpoint list with corrections applied.

Tips

• Include example request and response bodies for each endpoint for a more thorough review
• Consistency is more important than any single design choice - pick conventions and stick to them
• Think about your API from the consumer's perspective not the database structure
• The missing endpoints section often reveals gaps you won't notice until someone builds against your API