# API Contract

> Use for API changes that affect endpoints/DTOs/contracts. Do NOT implement unrelated business logic. Prefer backward-compatible changes.

- Skill: `askaret/api-contract` (Agent Skill)
- Install (CLI): `npx skillmds@latest add askaret/api-contract`
- Raw SKILL.md: https://api.skillmd.com/api/skills/askaret/api-contract/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: askaret (https://skillmd.com/u/askaret)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/askaret/api-contract

---


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