# API Horizontal Instructions
## Purpose
The API horizontal defines the external interface specifications for each vertical component. It serves as the contract between services, clients, and external systems, ensuring consistent communication patterns across the entire system.
## Content Requirements
### Required Sections
1. **Endpoint Definitions**
- HTTP methods (GET, POST, PUT, DELETE, PATCH)
- URL patterns and path parameters
- Query parameter specifications
- Request/response formats
2. **Authentication & Authorization**
- Authentication methods (JWT, API keys, OAuth)
- Authorization levels and permissions
- Security headers and requirements
3. **Request/Response Schemas**
- JSON schema definitions
- Content-Type specifications
- Error response formats
- Status code mappings
4. **Rate Limiting & Throttling**
- Request limits per time window
- Throttling strategies
- Quota management
5. **Versioning Strategy**
- Version numbering scheme
- Backward compatibility rules
- Deprecation timeline
### Documentation Format
```yaml
endpoints:
- path: "/api/v1/resource"
method: GET
description: "Retrieve resource collection"
parameters:
- name: "limit"
type: "integer"
required: false
description: "Maximum items to return"
responses:
200:
description: "Success"
schema: "ResourceCollection"
400:
description: "Bad Request"
schema: "ErrorResponse"
```
## Validation Rules
### Quality Control
1. **Completeness**
- All endpoints must have complete documentation
- All parameters must be typed and described
- All response codes must be documented
2. **Consistency**
- Naming conventions must be followed
- Response formats must be standardized
- Error handling must be uniform
3. **Security**
- All endpoints must specify authentication requirements
- Sensitive data handling must be documented
- Input validation rules must be explicit
4. **Performance**
- Response time expectations must be specified
- Caching strategies must be documented
- Resource usage limits must be defined
### Automated Checks
- OpenAPI 3.0+ specification compliance
- Schema validation against JSON Schema Draft 7+
- Security annotation completeness
- Breaking change detection
## Evolution Rules
### Across Verticals (Left to Right)
1. **Foundation → Core**
- Basic CRUD operations evolve into business logic APIs
- Simple schemas become domain-specific models
- Generic endpoints become specialized workflows
2. **Core → Integration**
- Internal APIs become external-facing endpoints
- Synchronous calls evolve into asynchronous patterns
- Single-tenant becomes multi-tenant aware
3. **Integration → Extension**
- Fixed APIs become configurable/pluggable
- Standard endpoints support custom extensions
- Monolithic APIs become microservice-aware
### Version Evolution
- **v1.0**: Basic CRUD with minimal validation
- **v2.0**: Business logic integration with enhanced security
- **v3.0**: Advanced features with performance optimization
- **v4.0**: Extension points with plugin architecture
## Dependencies
### Upstream Dependencies
1. **Schema Horizontal**
- Data models and type definitions
- Validation rules and constraints
- Relationship mappings
2. **Specs Horizontal**
- Business requirements and use cases
- Functional specifications
- Performance requirements
### Downstream Dependencies
1. **Tests Horizontal**
- API contract testing
- Integration test scenarios
- Performance benchmarks
2. **Frontend Horizontal**
- Client SDK generation
- Type definitions for TypeScript
- Mock data for development
3. **Backend Horizontal**
- Service implementation contracts
- Database interaction patterns
- Integration layer specifications
## Best Practices
### Design Principles
1. **RESTful Design**
- Use appropriate HTTP methods
- Follow resource-oriented URLs
- Implement proper status codes
2. **Consistency**
- Maintain naming conventions
- Use standardized error formats
- Apply uniform pagination patterns
3. **Security First**
- Implement authentication on all endpoints
- Validate all inputs
- Sanitize all outputs
4. **Performance Awareness**
- Design for caching
- Implement efficient pagination
- Support partial responses
### Common Patterns
```yaml
# Resource Collection Pattern
GET /api/v1/resources
- Supports filtering, sorting, pagination
- Returns standardized collection format
# Resource Item Pattern
GET /api/v1/resources/{id}
- Supports field selection
- Returns standardized item format
# Bulk Operations Pattern
POST /api/v1/resources/batch
- Accepts array of operations
- Returns batch operation results
# Asynchronous Operations Pattern
POST /api/v1/resources/{id}/actions/{action}
- Returns operation ID
- Provides status checking endpoint
```
## Integration Guidelines
### With Other Horizontals
1. **Schema Integration**
- Reference schema definitions in API specs
- Maintain consistency between API and database schemas
- Use schema validation in request/response handling
2. **Test Integration**
- Generate test cases from API specifications
- Implement contract testing
- Validate API behavior against specifications
3. **Documentation Integration**
- Generate interactive API documentation
- Provide code examples and SDKs
- Maintain up-to-date integration guides
### Tools and Standards
- **OpenAPI 3.0+** for specification format
- **JSON Schema** for data validation
- **Swagger UI** for documentation
- **Postman Collections** for testing
- **API Blueprint** for design-first development
