The client page: the nine semantic rules of the scenario-bundle API

Parent

Spec: #2454 — Document and teach the OEKG REST API. Derived from WF-14 decisions D5 and D8.

What to build

A client author reads one page and learns the behaviour a signature cannot express — the rules they would otherwise discover by hitting a 400. Everything mechanical (If-Match, ?confirm=, ?expand=, the 428/412/409 table, RDF negotiation) stays in the reference and is not restated here.

The nine rules:

1. A key absent from a payload means untouched, under every verb.
2. _meta is read-only and ignored on write.
3. Delete-by-omission exists on replace/ and nowhere else.
4. A bundle POST accepts nested sub-resources; a PATCH does not.
5. The delete's two guards cover two different accidents — stale state and wrong uuid — so neither is redundant ceremony.
6. A write is judged by the violations it introduces; a create is strict because it has no pre-state. A client seeing 400 on create where a PATCH succeeded otherwise reads it as a bug.
7. ref: table is reproducible, ref: dataset is current; a dead link stays and reads resolvable: false, which is correct rather than broken.
8. The server mints the uid; a stateless pipeline re-identifies with GET ?acronym=, which also yields the ETag.
9. _meta.history_recorded can read false inside a successful write — a named audit gap, not a status flag.

Acceptance criteria

• A new page under the OEKG API section carries all nine rules.
• Each rule has a worked request and response example.
• Each rule links the reference at its tag anchor rather than restating the endpoint table.
• The page does not repeat mechanical facts that the reference already carries as annotations.
• Changelog entry.

Blocked by

• #2459 — the endpoint-group tags — the rules link by tag anchor, so the anchors must be stable and singular first.

And by the API itself. Checked against the routes on develop (2026-09-15): four of the nine rules describe behaviour that does not exist yet, so this page cannot ship honestly before those slices land. The endpoints present today are the collection POST, the detail GET/PATCH, history, scenarios, study reports and dataset links — there is no DELETE, no replace/, no ?acronym= and no link resolution.

Those four slices are tracked in the maintainer's vault, not here. A page promising nine rules while four of them point at 404s would be worse than no page.

Start with the OEKG API section, the reference tag anchors from #2459, and the routes on develop; confirm which of the nine rules are currently documentable. Done means a new page includes all nine rules with worked request/response examples, reference links, no duplicated mechanical annotations, and a changelog entry after the blocked API slices land.