---
description: API validation and service standards
globs: ["services/**/*.java", "services/**/*.py", "services/**/*.js", "services/**/*.yml", "services/**/*.yaml", "services/**/*.xml", "services/**/*.json", "services/**/*.md", "services/**/Dockerfile*", "services/**/requirements.txt", "services/**/pom.xml"]
alwaysApply: false
---

# API Standards

When working with service files, follow these standards:

## Service Documentation
Each service MUST have comprehensive documentation:
- **API Gateway**: @services/api-gateway/README.md and @services/api-gateway/CLEAN_CODE.md
- **Service Adapters**: @services/service-adapters/README.md and @services/service-adapters/CLEAN_CODE.md
- **API Docs**: @services/api-docs/README.md and @services/api-docs/CLEAN_CODE.md

## Clean Code Implementation
Apply the principles detailed in each service's CLEAN_CODE.md:
- **Java Spring Boot**: Follow @services/api-gateway/CLEAN_CODE.md
- **Python FastAPI**: Follow @services/service-adapters/CLEAN_CODE.md
- **Node.js Express**: Follow @services/api-docs/CLEAN_CODE.md

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

## Error Handling
Use consistent error response format:
```javascript
{
  "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**: Constructor injection, proper validation, REST conventions
- **Python FastAPI**: Pydantic models, async/await, dependency injection
- **Node.js Express**: Middleware usage, error handling, health checks

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

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