ores.doc.http-recipe

One document that is both the page a reader opens and the source of the files the HTTP harness runs. A recipe is a literate document first: it says what an endpoint is for, the method and path it is addressed at, and the subject it forwards to. The Hurl file is the same document's export, so the prose and the runnable request cannot describe different endpoints.

The facet consumes a domain_entity model and writes one org document per model into =doc/recipes/http/<group>/. It reads the same route projection the generated route unit reads, so the document is a view of that unit rather than a second description of it: a route the unit gains arrives in the document that documents it, in the same commit.

The facet renders only where ores.cpp.http-route rendered something for the same model. That dependency is stated as #+requires_facet: rather than as a second per-model opt-in, because two flags for one decision drift: a model that opts into the route and not the document would ship endpoints with no recipe, and the reverse would ship a recipe for endpoints that do not exist.

Opt-in is the route's, in other words: :ores.cpp.http-route.enabled: in the model's properties drawer, and :http_route: true on a message for an operation. The facet itself is enabled by default and resolves to nothing wherever the route does.

Each endpoint's block carries :tangle <name>.hurl. The tangle run honours that per block and moves the result into projects/ores.http/scripts/library/<group>/, so the document states the file's name and the build owns its directory. Target =compass build --direct tangle_http_recipes.

A recipe states no host, no port and no credential. base_url and token are Hurl variables the runner supplies, which is what lets the same committed file run against any environment.

• ores.doc — the parent technical space's catalogue of documentation facets.
• ores.cpp.http-route — the unit this facet documents.
• ores.doc.shell-recipe — the same arrangement for the shell surface.