Initial commit

backend-api.md

@@ -0,0 +1,25 @@
+---
+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.