HTTP & APIs

Call APIs with the http function - headers, query params, JSON bodies and parsed responses

The http function makes requests and hands you a parsed response. All fields below were verified against a live endpoint.

GET with query and headers

- name: fetch_page
  func: http
  args:
    url: "https://httpbin.org/get"
    method: GET
    query:
      page: "1"
    headers:
      X-Request-Id: "req-123"
    timeout: 15s
  outputs:
    status: "{{ result.status_code }}"
    page: "{{ result.data_object.args.page }}"

When the response is JSON, result.data_object is the parsed body - reach into it with dot paths. result.body always holds the raw text.

POST with a JSON body

YAML maps under body: are sent as JSON:

- name: create_item
  func: http
  args:
    url: "https://httpbin.org/post"
    method: POST
    body:
      name: "widget"
      qty: 3
  outputs:
    echoed: "{{ result.data_object.json.name }}"

Assert on responses

- name: verify_api
  func: assert
  args:
    conditions:
      - condition: '{{ eq steps.fetch_page.status 200 }}'
        desc: "endpoint is up"
      - condition: '{{ eq steps.create_item.echoed "widget" }}'
        desc: "payload round-tripped"

Resilient API calls

Combine with what you learned in error handling:

- name: poll_deploy_status
  func: http
  args:
    url: "https://api.example.com/deploys/latest"
    timeout: 10s
  retry:
    max_attempts: 5
    interval: "1s"
    backoff_rate: 2.0
    max_delay: "15s"

Run it

orchstep run

Where to go next

Environments - run the same workflow against dev, staging and production.

< Error Handling Environments >