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.

  1. Gather requirements: entity name, domain, operations needed (list/save/delete/history), authorisation (.auth_required(), .roles(...)), OpenAPI tags and summaries.
  2. 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.
  3. Phase 2 — delete + history: add delete (batch) and history handlers; register routes. PR title: [http] Add {entity} delete and history.
  4. Phase 3 — recipe docs: add how_do_i_*.org recipes under doc/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

Reference

Codegen gap

❌ No codegen profile exists for ores.http.server. Do not hand-code this layer. When entity-creator reaches this layer:

  1. Raise a sprint story: "Implement codegen profile for HTTP endpoints."
  2. Reference Entity lifecycle§"Codegen gaps" for what the profile must cover.
  3. Link the story to the entity task before marking this layer done.
  4. Once the profile is merged, regenerate and discard any hand-written code.

Until the gap is resolved, this layer is incomplete.

Emacs 29.1 (Org mode 9.6.6)