Rules:
- •Start from the contract boundary (endpoint/controller + DTOs + OpenAPI/Swagger + client usage).
- •Prefer additive changes (new fields/endpoints) over breaking changes.
- •Standardize errors and status codes consistently across endpoints (use Problem Details where applicable).
- •If contract changes: update docs and any generated clients/types.
Checklist:
- •Endpoint changes
- •route, method, auth requirements
- •request/response DTO changes
- •validation rules and error mapping
- •Compatibility
- •additive vs breaking
- •default values for new fields
- •deprecation plan if needed (headers, docs, versioning)
- •Error handling
- •status codes consistent with repo conventions
- •Problem Details shape consistent across API
- •no sensitive data in error messages
- •Documentation
- •OpenAPI/Swagger updated and accurate
- •examples updated if repo uses them
- •Consumers
- •update frontend/client code and any SDK/client generation
- •update contract/integration tests
Finish with:
- •Contract diff summary (what changed and why)
- •Commands run + results
- •Manual verification steps
- •Risks/follow-ups