HTTP facet

Table of Contents

HTTP entity endpoints live in ores.http.server under src/routes/{domain}_routes.cpp. Every entity gets a routes class that registers list, save, delete, and history handlers with the async router. All handlers are boost::asio::awaitable coroutines; authentication and authorisation are declared on the route builder, not inside the handler body. Return to Knowledge.

Codegen gap

⚠ No codegen profile exists for this layer. Before creating HTTP endpoints for any new entity:

  1. Create mustache templates in projects/ores.codegen/library/templates/.
  2. Add an http profile entry to facet_catalogue.org.
  3. Validate against an existing entity (e.g. currency).
  4. Only then use codegen to generate the layer.

Until the profile exists, see the recipes for the manual path — but treat this as a workaround, not the target state.

Route structure

Each entity routes class exposes a standard set of endpoints:

Method Path Handler Notes
GET /api/v1/{entities} handle_get_{entities} Paginated list; offset + limit query params
POST /api/v1/{entities} handle_save_{entity} Upsert; body is the domain object as JSON
DELETE /api/v1/{entities} handle_delete_{entities} Batch delete by ID array in body
GET /api/v1/{entities}/{id}/history handle_get_{entity}_history All versions of a single entity

Phase 1 delivers list + save; Phase 2 delivers delete + history; Phase 3 adds recipe docs.

Handler skeleton

Key conventions for every handler:

  • Class is final; constructor takes database::context + shared services.
  • Logger: inline static std::string_view logger_name with fully qualified path; static accessor returns a local singleton.
  • All handler declarations go in the private section of the header.
  • Include <rfl/json.hpp> and ores.utility/rfl/reflectors.hpp for request/response serialisation.
  • Return co_return http_response::ok(body) or co_return http_response::error(...).

Authorisation hooks

Declare auth and roles on the route builder, not in the handler: call .auth_required() and .roles(...) on the route, then add .query_param(...) for pagination parameters (offset, limit) and .response<...>() for the response type.

File locations

File Path
Header projects/ores.http.server/include/ores.http.server/routes/{domain}_routes.hpp
Implementation projects/ores.http.server/src/routes/{domain}_routes.cpp
Registration projects/ores.http.server/src/application.cpp

See also

Emacs 29.1 (Org mode 9.6.6)