Codegen Add HTTP Entity
Table of Contents
When to use this skill
When you need to add HTTP REST API endpoints for a new entity in
ores.http.server. Prerequisites: the domain type must exist (domain-type-creator),
the service layer must be implemented, and JSON serialisation via rfl
must be available. See Entity lifecycle for the full layer ordering.
How to use this skill
The work is split into three phases, each ending in a PR.
- Gather requirements: entity name, domain, operations needed
(list/save/delete/history), authorisation (
.auth_required(),.roles(...)), OpenAPI tags and summaries. - Phase 1 — list + save: create or extend the routes class header
and implementation; register routes in
application.cpp. PR title:[http] Add {entity} list and save endpoints. - Phase 2 — delete + history: add delete (batch) and history
handlers; register routes. PR title:
[http] Add {entity} delete and history. - Phase 3 — recipe docs: add
how_do_i_*.orgrecipes underdoc/recipes/http/. PR title:[doc] Add {entity} HTTP endpoint recipes.
Use feature-branch-manager between phases and pr-manager to open each PR.
Build after every step: cmake --build --preset linux-clang-debug-ninja --target ores.http.server.lib.
Recipes
- How do I create HTTP endpoints for a new entity? — phase-by-phase walkthrough.
Reference
- HTTP entity patterns — route structure, handler skeleton, auth hooks, file locations.
- Entity lifecycle — layer ordering overview.
- domain-type-creator — prerequisite first layer.
Codegen gap
❌ No codegen profile exists for ores.http.server. Do not hand-code
this layer. When entity-creator reaches this layer:
- Raise a sprint story: "Implement codegen profile for HTTP endpoints."
- Reference Entity lifecycle§"Codegen gaps" for what the profile must cover.
- Link the story to the entity task before marking this layer done.
- Once the profile is merged, regenerate and discard any hand-written code.
Until the gap is resolved, this layer is incomplete.