Versioning and compatibility
SREDSimplify currently uses path-based API versioning.
Current versioned surfaces
| Surface | Current versioning shape |
|---|---|
| Main backend API | /api/v1/** |
| Internal backend APIs | /internal/api/v1/** |
| Python worker API | /api/v1/** inside the worker service |
| Frontend browser path | /api/bff/api/v1/* proxied to backend /api/v1/* |
Current compatibility posture
Today the repository reflects a single active API generation: v1.
That means:
- new endpoints should land under
/api/v1/**unless a deliberate breaking boundary is introduced - existing clients should not assume silent path renames
- breaking changes should be treated as explicit engineering work, not incidental refactors
What counts as a breaking change
Examples that should trigger deliberate review:
- removing or renaming an existing endpoint
- changing required request fields
- changing authentication requirements on an established route
- changing response envelope shape in a way that breaks existing clients
- changing webhook payload assumptions without migration guidance
For cross-service contracts such as Java-to-Python task envelopes, treat breaking changes as architecture-level changes and capture them in an ADR when the boundary meaningfully shifts.
What is documented vs generated
- Generated Swagger/OpenAPI is the live endpoint inventory
- These hand-written pages define the expected compatibility posture for humans reading the repo
If the generated docs and the hand-written contract pages disagree, fix the docs in the same change that modifies the API.
Deprecation guidance
There is no separate published deprecation policy document in this repo yet. Until one exists:
- prefer additive changes over breaking changes
- keep old routes working while frontend and internal callers migrate
- document any compatibility caveat in the API docs and changelog
- update Engineering conventions or add an ADR when the change alters long-lived expectations