API Development Guidelines

apibackendrest

API design principles and conventions for building consistent, well-documented, and maintainable backend APIs.

Целевые файлы

Файл	Формат
.cursorrules	plaintext
CLAUDE.md	markdown

Содержимое

API style: ${api_style}. Follow established conventions for the chosen paradigm consistently across all endpoints. Use consistent resource naming: plural nouns for collections (/users, /orders), nested routes for relationships (/users/:id/orders). Always version your API: use URL path versioning (/api/v1/) or Accept header versioning. Never break existing clients without a deprecation period. Return appropriate HTTP status codes: 200 (OK), 201 (Created), 204 (No Content), 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 422 (Unprocessable Entity), 500 (Internal Server Error). Use a consistent error response format: { "error": { "code": "VALIDATION_ERROR", "message": "Human-readable message", "details": [...] } }. Implement pagination for all list endpoints. Support cursor-based or offset-based pagination with limit, offset/cursor parameters. Validate all input at the API boundary. Return 400/422 with clear error messages listing every invalid field — not just the first one. Document every endpoint with OpenAPI/Swagger. Include request/response examples, authentication requirements, and rate limit info. Support filtering, sorting, and field selection where appropriate: ?sort=-created_at&fields=id,name&status=active. Implement rate limiting and return 429 (Too Many Requests) with Retry-After header. Log excessive request patterns for abuse detection.