How do I create HTTP endpoints for a new entity?
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):
- Add handler declarations to
include/ores.http.server/routes/{domain}_routes.hpp(or create the routes class if it doesn't exist). - Implement
handle_get_{entities}(paginated GET) andhandle_save_{entity}(POST upsert) insrc/routes/{domain}_routes.cpp. - Register both routes in
register_routes()using the router builder (.auth_required(),.roles(...),.query_param(...),.response<T>()). - Register the routes class in
src/application.cpp. - 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):
- Add
handle_delete_{entities}(DELETE batch) andhandle_get_{entity}_history(GET /{id}/history) declarations. - Implement both handlers; register routes in
register_routes(). - Build and verify.
Phase 3 — recipe docs (PR title: [doc] Add {entity} HTTP endpoint recipes):
- Add per-operation recipe files under
doc/recipes/http/(one per endpoint, following thehow_do_i_*.orgnaming convention).
Tested by
Build ores.http.server.lib cleanly and run the HTTP integration tests.
See also
- HTTP entity patterns — route structure, handler conventions, auth hooks.
- codegen-add-http-entity — skill that drives this workflow.
- Entity lifecycle — layer ordering overview.