25 lines
1.3 KiB
Markdown
25 lines
1.3 KiB
Markdown
---
|
|
trigger: always_on
|
|
---
|
|
|
|
# Backend API Rules
|
|
|
|
## Development Phase (Pre-deployment)
|
|
- Breaking changes are allowed without deprecation.
|
|
- Route versioning is optional during this phase. You may:
|
|
- Use unversioned routes (e.g., `/api/*`) while iterating, or
|
|
- Use a provisional version like `/api/v0/*`.
|
|
- Pydantic (v2) schemas are the source of truth for all request/response payloads.
|
|
- Keep schema examples updated when fields or validation rules change.
|
|
- Keep OpenAPI docs at `/docs` current with every API change.
|
|
- Document API changes succinctly with each PR and add brief migration notes to `docs/api/` (e.g., `docs/api/CHANGELOG.md`) as needed.
|
|
|
|
## Post-deployment Policy (Stabilized)
|
|
- Adopt versioned routes under `api/v1/*` and beyond.
|
|
- No breaking changes to `v1` without deprecation; introduce `v2` (or later) for breaking changes.
|
|
- Maintain deprecation notices and migration guidance in `docs/api/`.
|
|
|
|
## Consistency and Quality
|
|
- Schemas define types, validation, and examples; align handler implementations strictly with schemas.
|
|
- Ensure error responses are documented (shape and examples) and include correlation IDs in responses/logs if available.
|
|
- Keep auto-generated docs (`/docs`) accurate and readable; ensure example payloads are representative and valid. |