Platform api

HTTP API testing backend — session, base URL, headers, form queue, last response

Platform: api routes to the HTTP API backend (engine/api/). Handlers call an HTTP session, not a browser.

Headers

Platform: api

Group: Orders API

Scenario: Create order
  When I api set header "Authorization" to "Bearer $API_TOKEN"
  When I api post "/orders" with body '{"item":"book"}'
  Then I api should status "201"
  And I api should json path "$.id" exist
  When I store "@order-id" from api json "$.id"
  When I api get "/orders"
  Then I api should status "200"

Multipart form queue

Prepare text fields and files on the session, then send with a bare api post / put / patch (no with body). The queue clears after a successful send.

When I api set fields to '{"folder":"docs","type":"invoice"}'
When I api set field "name" to "Invoice"
When I api set file "main" to "invoice.pdf"
When I api set file "extra" to "receipt.pdf"
When I api post "/upload"
Then I api should status "201"

Rule	Behavior
Text	`api set field` (one key) or `api set fields` (JSON object)
Files	`api set file "<field>" to "<basename>"` — repeat for multi-file
Send	Bare `api post` / `put` / `patch` builds `multipart/form-data`
Conflicts	Pending form + `with body` / `with body file` → error
Pending form	`api get` / `api delete` fail until you send (or do not leave a queue)

File basenames resolve beside the .stk (then files/), same as upload.

Poll until JSON

Re-issue the last API request until a gjson path equals the expected value:

When I api get "/jobs/@job-id"
And I api wait until json path "$.status" be "ready"

Authors usually api get the status URL first, then api wait. Distinct from one-shot api should json path … be and from UI wait for response.

Session

Concern	Behavior
Base URL	`$API_BASE_URL` (env / `.env` / vars)
Headers	`api set header "…" to "…"` on the session
Form queue	Fields + files until the next multipart send
Last response	Status, body, JSON path asserts + `store … from api json`
Reports	Method/URL/status logged; `Authorization` and secret headers redacted

Commands

api get
api post / put / patch / delete
api set header
api set field / api set fields / api set file
api should
api wait
store with from api json

Notes

One file = one platform. Do not mix web / mobile / api in a single .stk for v1.
Asserts and store … from api json always use the last response — assert or store before the next request if you need earlier data.
Still planned: query helpers, schema/OpenAPI validate, GraphQL.
Distinct from UI network waits / route mocking.