Contracts: one version per surface (admin, delivery, per module) in the header and /api/meta
- Dominant language
- C#
- Stars
- 6
- Forks
- 7
- Avg merge
- 4h 42m
- Merged PRs (30d)
- 307
Description
There is one HTTP contract version for everything the API serves. `barakoCMS/Features/Monitoring/Meta/ApiContract.cs` holds a single `Version`, sent as `X-Api-Contract-Version` on every response (`barakoCMS/Extensions/ServiceCollectionExtensions.cs:1206-1215`) and in `/api/meta` (`barakoCMS/Features/Monitoring/Meta/Models.cs:10`). barakoBrew keeps its accepted range by hand, barakoPress checks only the Pages body shape and never the header, and barako-client checks nothing.
### Why it matters
An admin-only change moves the one number, so every console refuses to run, and every renderer that did check would refuse too, even though delivery did not change. #867 (a locked account answered like any failed sign-in) is exactly that: an admin sign-in change that bumps the version the renderer would read. A module's own endpoints cannot move on their own cadence either.
### The general concept
One version per surface: admin, delivery, and one per module that has endpoints. Each is reported in `/api/meta` and in a header, and each consumer checks only the surfaces it reads. Consumer ranges are declared in the deploy recipe (BaryoVM #88), so a deploy refuses a set of images that do not fit.
### Where it lives
Core: meta, and the contract rule in CLAUDE.md section 6. Modules declare their own surface version.
### Compatibility
Released. `X-Api-Contract-Version` and `ApiContractVersion` keep their meaning as the admin version, so the console's check keeps working. New headers and meta fields for delivery and modules are additive. Relates #631, #187 and #629.
### Done when
- An admin-only contract change leaves the delivery version unchanged, and a test pins both numbers so a change to one without the other is visible.
- `/api/meta` lists a version for each module that has endpoints.
- CLAUDE.md section 6 says which surface a given change moves.
Found in the architecture sweep of 15 September 2026.
Contributor guide
Research direction
Start with barakoCMS/Features/Monitoring/Meta/ApiContract.cs, barakoCMS/Extensions/ServiceCollectionExtensions.cs:1206-1215, barakoCMS/Features/Monitoring/Meta/Models.cs:10, and CLAUDE.md section 6 to trace the current version and metadata behavior. Done means admin, delivery, and endpoint-bearing module versions are represented as specified, admin-only changes leave delivery unchanged with a test covering both, and the contract rule documents which surface changes.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp
- Domain
- api, backend
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100