1.3 KiB
1.3 KiB
trigger
| 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/*.
- Use unversioned routes (e.g.,
- 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
/docscurrent 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
v1without deprecation; introducev2(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.