Graphden documentation

Lesson 38 — HTTP calls by function identity

Goal: name a published handler by UUID, resolve its public URL, make an actual HTTP GET, and receive a changed response after editing the graph.

You need: the authenticated finite HTTP host from lesson 35. Ordinary cloud users can take this lesson; it creates no persistent service or listener port.

Try it

  1. Extend text-ok-response as tutorial-contract-answer and bind its :body to hello. Choose ⋯ → HTTP → Publish for 30 minutes.
  2. Extend service-endpoint as tutorial-http-address. Bind its :service slot with Bind fn-ref to tutorial-contract-answer. This stores the handler UUID without executing it.
  3. Run the address function and confirm the database effect if requested. Read its result: host, port, and url. Keep the whole URL, including any publication path. On a deployment behind TLS this is an HTTPS URL.
  4. After Run finishes, copy that URL into another browser tab. The real HTTP response must show hello. Return to the editor.
  5. Edit the handler’s bound literal to updated and save. Leave its publication and the address function’s fn-ref unchanged.
  6. Reload the same public tab. Its response must now be updated.
  7. Stop the publication through ⋯ → HTTP. Reload its URL to verify it is unavailable, then finish the lesson and remove its created items.

These requests run sequentially, so the exercise also works with one execution slot. A busy executor may return 503: finish another run and retry. The browser request is real HTTP, and the published handler still obeys its execution quota, current permissions, effect restrictions, and deadline.

Calling from a graph

service-get composes the same identity resolution with an ordinary outbound HTTP GET. Bind :service to the handler’s fn-ref and :path to /hello. Its result contains the HTTP status, headers and body. Network permissions, outbound address checks, rate limits and timeouts still apply.

A graph calling a handler on its own executor needs capacity for both calls: its Run holds an execution slot and worker while waiting for the HTTP response. With one organization slot, the handler returns 503. A saturated shared worker pool can also cause a timeout. Use sufficient capacity or a separately hosted endpoint for such nested calls; publishing does not increase these limits.

Core resolves a base URL containing its reserved publication path; cloud resolves an isolated apps origin. Do not strip that base path when building a request. Never put a private bearer token in the public URL. The handler receives sanitized request fields and returns bounded plain text or JSON.

The same identity seam for persistent services

On a self-hosted or dedicated executor, service-endpoint first prefers an active listener instance on the caller’s branch. The reconciler maintains its host, port and heartbeat. A temporary publication is a separate fallback, and an ordinary configured cloud app may also resolve through the existing addon. The function UUID still names the target without invoking it. No active endpoint means service/not-running; it does not guess another branch.

The following sections describe shared contracts and the existing persistent service model. Temporary publications do not create service-instance rows or promise persistent-service tracing.

The contract lives in the graph

For a larger application, define a path once, then reference it from both the producer and consumer:

;; svc-orders.api — shared path, owned by the producer's team
{:name :orders-path :parent :const :args {:value "/orders"}}

;; the producer's route, built from the contract
{:name :orders-route :parent :get-route
 :args {:path :orders-path :handler :orders-ok}}

;; the consumer, built from the same contract
{:name :fetch-orders :parent :service-get-json
 :args {:service :orders-service :path :orders-path}}

Change the path constant’s value and both the route and consumer use the new path. orders-ok and orders-service stand for your existing producer handler and service.

Sharing a response shape requires another explicit connection: declare a type such as {:name :orders-shape :type {:orders [:list :int]}} and use it in the producing function’s return contract and consuming arguments. An unused type declaration cannot diagnose either graph. service-get-json only parses JSON; validate external data with ensure-type before relying on its shape. See types and TYPES.md — Typed and Untyped Boundary.

With two teams in one org, the contract namespace belongs to the producer’s team and the consumer’s team holds read on it (lesson 28 — a role can be the grant’s subject, so the team is one row).

On a multi-pod fleet, and on the cloud

Following a call across services

For persistent HTTP services, Trace (lesson 18) can follow a call beyond :http-get. Run :fetch-orders from the Run pane and open the run’s result: under it, a Downstream calls list names :orders-ring, the producer’s handler, with its status. Open the producer’s Runs tab: the request :fetch-orders made is a run of its own there, and its details show the same trace id as the caller.

The mechanics: a persisted run knows its id; :service-get sends it along as X-Graphden-Trace; :http-server sees the header and records the request it handles as an execution linked to the caller (a request without the header is not recorded — normal traffic pays nothing). Every hop shares the top-level run’s trace id, so a chain A → B → C is one tree you can walk from A (docs/EXECUTION.md § Tracing across services).

What we glossed over

Next

Lesson 39 — Queues: asynchronous work between services.