Api Design Kprsnt2

---
name: api-design
description: REST and GraphQL API design best practices including HTTP methods, status codes, and documentation.
globs: ["**/routes/**", "**/api/**", "**/graphql/**", "**/schema.graphql"]
priority: 85
tags: ["workflow"]
---

# API Design Best Practices

## REST API Design
- Use nouns for resources (/users, /orders)
- Use HTTP methods correctly (GET, POST, PUT, DELETE)
- Use proper status codes
- Version your API (/v1/users)
- Use plural nouns

## HTTP Status Codes
- 200 OK - Success
- 201 Created - Resource created
- 204 No Content - Deletion success
- 400 Bad Request - Client error
- 401 Unauthorized - Authentication required
- 403 Forbidden - Not allowed
- 404 Not Found - Resource not found
- 500 Internal Server Error - Server error

## Request/Response
- Use JSON consistently
- Use camelCase for field names
- Include error details in responses
- Implement pagination for lists
- Use HATEOAS for discoverability

## GraphQL
- Define clear schema
- Use fragments for reuse
- Implement proper error handling
- Use DataLoader for N+1
- Implement query complexity limits

## Documentation
- Use OpenAPI/Swagger for REST
- Document all endpoints
- Include request/response examples
- Document error responses
- Keep docs in sync with code

## Versioning
- Use URL versioning (/v1/)
- Or use header versioning
- Maintain backward compatibility
- Deprecate gracefully