gps-denied-desktop/.cursor/commands/2.planning/2.25_plan_api_contracts.md

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