Skip to content

External services

Declare downstream HTTP services in application.yaml and call them through a typed client with auth and header propagation wired in.

external_services:
  payments:
    serverUrl: https://api.payments.com   # or server_url
    basePath: /v1                          # or base_path
    timeout: 30
    propagate_headers: [x-request-id, authorization]
    auth:
      type: bearer                         # none | basic | bearer | api_key | oauth2
      token: ${PAYMENTS_TOKEN}

from langstitch import get_http_client, set_request_headers

# In request middleware, record inbound headers once:
set_request_headers(request.headers)

api = get_http_client("payments")   # base_url, timeout, auth + propagated headers wired in

The ServiceClient API

The returned ServiceClient covers all HTTP verbs with {path} templating and per-request header/query merging (auth + propagated headers stay applied):

api.get("/users/{id}", path_params={"id": 7}, params={"expand": "wallet"})
api.post("/users", json={"name": "Ada"}, headers={"X-Trace": "1"})
api.put("/users/{id}", path_params={"id": 7}, json={...})
api.patch("/users/{id}", path_params={"id": 7}, json={...})
api.delete("/users/{id}", path_params={"id": 7})
api.request("OPTIONS", "/users")

api.set_header("X-Tenant", "acme")      # mutate default headers
api.add_headers({"X-Region": "eu"})

get_async_http_client("payments") returns the awaitable AsyncServiceClient equivalent. Pass raw=True to either for the underlying httpx client.

Auth types

String values support ${ENV_VAR} interpolation.

auth.type Options Effect
none — no credentials
basic username, password Authorization: Basic <b64>
bearer token Authorization: Bearer <token>
api_key name (default X-API-Key), value, in (header|query) header or query param
oauth2 token_url, client_id, client_secret, scope?, audience? client-credentials; token fetched + cached/refreshed automatically

Header propagation

propagate_headers forwards the listed inbound request headers (case-insensitive) onto the outbound client. Call set_request_headers(request.headers) once per inbound request (in middleware) to enable it.

Don't over-propagate

Only list headers a service should actually receive. Forwarding authorization to a third-party host can leak credentials — scope propagate_headers per service.