How do I create HTTP endpoints for a new entity?

Table of Contents

Route structure, handler skeleton, and auth conventions are in HTTP entity patterns. The codegen-add-http-entity skill drives this process.

Question

How do I add HTTP REST endpoints for a new entity in ores.http.server?

Answer

Phase 1 — list and save (PR title: [http] Add {entity} list and save endpoints):

  1. Add handler declarations to include/ores.http.server/routes/{domain}_routes.hpp (or create the routes class if it doesn't exist).
  2. Implement handle_get_{entities} (paginated GET) and handle_save_{entity} (POST upsert) in src/routes/{domain}_routes.cpp.
  3. Register both routes in register_routes() using the router builder (.auth_required(), .roles(...), .query_param(...), .response<T>()).
  4. Register the routes class in src/application.cpp.
  5. Build: cmake --build --preset linux-clang-debug-ninja --target ores.http.server.lib

Phase 2 — delete and history (PR title: [http] Add {entity} delete and history):

  1. Add handle_delete_{entities} (DELETE batch) and handle_get_{entity}_history (GET /{id}/history) declarations.
  2. Implement both handlers; register routes in register_routes().
  3. Build and verify.

Phase 3 — recipe docs (PR title: [doc] Add {entity} HTTP endpoint recipes):

  1. Add per-operation recipe files under doc/recipes/http/ (one per endpoint, following the how_do_i_*.org naming convention).

Tested by

Build ores.http.server.lib cleanly and run the HTTP integration tests.

See also

Emacs 29.1 (Org mode 9.6.6)