Skip to content

AI agent guide — authoring rest.yaml

At a glance

  • Read this if you are an AI agent asked to add or change an HTTP endpoint. It is the context you need — you should not have to read the parser source.
  • Generate from rules. The REST grammar and its machine-readable form rest-automation.json are the source of truth.
  • rest.yaml is parsed and validated at startup (RoutingEntry); an invalid entry fails to load.

Decide the binding first

Pick how the endpoint reaches its backend, then fill the entry:

  • Function → service: <function.route>.
  • Flow → service: http.flow.adapter and flow: <flow-id>.
  • HTTP relay → service: https://host (single URL; url_rewrite/trust_all_cert allowed).

Generate deterministically

Look up exact fields/values in rest-automation.json; follow the rules in rest-grammar.md. Then verify:

Pre-write checklist - [ ] The entry has service, methods, and url. - [ ] methods are from GET PUT POST DELETE HEAD PATCH — do not list OPTIONS (auto-added). - [ ] Binding is consistent: a flow uses service: http.flow.adapter; an http(s):// relay service is a single URL. - [ ] Any cors:/headers: value matches an existing cors/headers id in the same file. - [ ] url_rewrite (if present) is a list of exactly two strings, and only on a relay service. - [ ] {param} tokens in url are balanced and not nested.

Worked example

The canonical example below covers all three binding forms — a flow-backed endpoint with reusable CORS and response-header configs, a function-backed endpoint with a path parameter, and an HTTP relay with url_rewrite. This exact file is also loaded through the production RoutingEntry parser in a platform-core test, so the example cannot drift from the router:

# The canonical rest.yaml worked example for the documentation guides.
#
# This exact file is included into the guides by mkdocs AND loaded through the production
# RoutingEntry parser in RoutingEntryGuideFixtureTest, so the documented example can never
# drift from what the REST automation engine actually accepts.

rest:
  # A flow-backed endpoint needs BOTH keys: 'service' selects the flow adapter and
  # 'flow' selects the flow. An entry with 'flow' alone has no service and is
  # skipped as invalid at startup.
  - service: 'http.flow.adapter'
    flow: 'order-status'
    methods: ['POST']
    url: '/api/orders/{order_id}/status'
    timeout: 30s
    cors: cors_1
    headers: header_1
    tracing: true

  # A function-backed endpoint with a path parameter
  - service: 'profile.lookup'
    methods: ['GET']
    url: '/api/profile/{id}'
    timeout: 10s

  # An HTTP relay: 'service' is a single URL and 'url_rewrite' maps the inbound
  # path prefix to the upstream path
  - service: 'https://example.org'
    methods: ['GET']
    url: '/api/upstream/orders'
    url_rewrite: ['/api/upstream', '/v1']
    timeout: 20s
    tracing: true

cors:
  - id: cors_1
    options:
      - 'Access-Control-Allow-Origin: *'
      - 'Access-Control-Allow-Methods: GET, POST, OPTIONS'
      - 'Access-Control-Allow-Headers: Origin, Authorization, Content-Type'
    headers:
      - 'Access-Control-Allow-Origin: *'

headers:
  - id: header_1
    response:
      add:
        - 'x-powered-by: mercury'
      drop:
        - 'server'

A traced endpoint serving a legacy caller that uses its own trace/correlation header names (per-endpoint impedance matching — the optional trace.id.header / correlation.id.header / traceparent.header keys override the global http.trace.id.header / http.correlation.id.header / http.traceparent.header names for this entry only; the standard W3C traceparent always takes precedence, and a custom traceparent.header name is read only when the standard header is absent. These overrides are for backward compatibility with legacy systems only — the standard W3C/OTel traceparent needs no configuration and departing from it is discouraged):

rest:
  - service: 'legacy.orders'
    methods: ['POST']
    url: '/api/legacy/orders'
    timeout: 15s
    tracing: true
    trace.id.header: 'X-Legacy-Trace'
    correlation.id.header: 'X-Legacy-Cid'

See also