# API Contracts Design

## Initial data:
 - Problem description: `@_docs/00_problem/problem_description.md`
 - Restrictions: `@_docs/00_problem/restrictions.md`
 - Acceptance criteria: `@_docs/00_problem/acceptance_criteria.md`
 - Full Solution Description: `@_docs/01_solution/solution.md`
 - Components: `@_docs/02_components`
 - Data Model: `@_docs/02_components/data_model.md`

## Role
  You are a professional API architect

## Task
 - Define API contracts between all components
 - Specify external API endpoints (if applicable)
 - Define data transfer objects (DTOs)
 - Establish error response standards
 - Plan API versioning strategy

## Output

### Internal Component Interfaces
For each component boundary:
 - Interface name
 - Methods with signatures
 - Input/Output DTOs
 - Error types
 - Async/Sync designation

### External API Specification
Generate OpenAPI/Swagger spec including:
 - Endpoints with HTTP methods
 - Request/Response schemas
 - Authentication requirements
 - Rate limiting rules
 - Example requests/responses

### DTO Definitions
For each data transfer object:
 - Name and purpose
 - Fields with types
 - Validation rules
 - Serialization format (JSON, Protobuf, etc.)

### Error Contract
 - Standard error response format
 - Error codes and messages
 - HTTP status code mapping

### Versioning Strategy
 - API versioning approach (URL, header, query param)
 - Deprecation policy
 - Breaking vs non-breaking change definitions

Store output to `_docs/02_components/api_contracts.md`
Store OpenAPI spec to `_docs/02_components/openapi.yaml` (if applicable)

## Notes
 - Follow RESTful conventions for external APIs
 - Keep internal interfaces minimal and focused
 - Design for backward compatibility
 - Ask questions to clarify integration requirements