---
description: API validation and service standards
globs: ["services/**/*.java", "services/**/*.py", "services/**/*.js"]
alwaysApply: false
---

# API Standards

## API Documentation

### OpenAPI Requirements
- All endpoints MUST have OpenAPI documentation
- Include request/response schemas
- Provide example requests and responses
- Document error responses
- Include authentication requirements

### Documentation Tags
- Use consistent tags for endpoint grouping
- Provide clear descriptions
- Include parameter documentation
- Document response codes

## Error Handling

### Consistent Error Responses
```javascript
// Standard error response format
{
  "error": "Error type",
  "message": "User-friendly message",
  "timestamp": "2024-01-01T00:00:00Z",
  "details": "Additional error details"
}
```

### HTTP Status Codes
- 200: Success
- 201: Created
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
- 503: Service Unavailable

## Service-Specific Standards

### Java Spring Boot
- Use constructor injection
- Implement proper validation
- Use appropriate annotations
- Follow REST conventions
- Implement global exception handling

### Python FastAPI
- Use Pydantic models
- Implement async/await
- Use dependency injection
- Follow OpenAPI standards
- Implement proper error handling

### Node.js Express
- Use middleware appropriately
- Implement proper error handling
- Use async/await patterns
- Follow REST conventions
- Implement health checks

## Validation

### Input Validation
- Validate all inputs
- Sanitize user data
- Use appropriate data types
- Implement rate limiting

### Response Validation
- Validate response schemas
- Use consistent data formats
- Implement proper error handling
- Document response structures

## Performance

### API Performance
- Use pagination for large datasets
- Implement response compression
- Use appropriate HTTP methods
- Optimize response sizes

### Caching
- Implement appropriate caching
- Use Redis for distributed caching
- Cache frequently accessed data
- Implement cache invalidation