BaryoDev / BaryoDev/barakoCMS

Contracts: one version per surface (admin, delivery, per module) in the header and /api/meta

Open
#902 0 comments 0 reactions 0 assignees View on GitHub
core design
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.