Request instances

Path: apis/<api>/resources/<resource>/requests/<name>.json (operation-bound) or apis/<api>/requests/<name>.json (standalone).

A request instance is a concrete, runnable call: an operation plus actual values. The current format is version 2. (Version 1 files are migrated to v2 automatically when read.)

Example: bound to an operation

{
  "version": 2,
  "name": "create-pet",
  "operation": { "resource": "Pet", "name": "create" },
  "params": {
    "header": { "X-Trace-Id": { "value": "abc123", "enabled": true } }
  },
  "body": {
    "contentType": "application/json",
    "data": { "name": "Rufus", "photoUrls": ["example.com"], "status": "available" }
  },
  "auth": { "type": "apiKey", "in": "header", "name": "api_key", "value": "{{apiKey}}" }
}

Example: standalone (inline)

{
  "version": 2,
  "name": "quick-inventory-check",
  "operation": { "method": "GET", "url": "{{baseUrl}}/store/inventory" }
}

Fields

visibility is not stored in the file; it's derived from the filename prefix. See Instance visibility.

operation

Reference an existing spec operation:

{ "resource": "Pet", "name": "get" }

Or define the call inline (standalone requests with no spec operation):

{ "method": "GET", "url": "{{baseUrl}}/store/inventory" }

params

Grouped by location: path, query, header, cookie. Each parameter is an object with a value and an enabled flag, so a parameter can be present but toggled off:

"params": {
  "path": { "petId": { "value": "10", "enabled": true } },
  "header": { "X-Trace-Id": { "value": "abc", "enabled": true } }
}

Values may contain {{variables}}, resolved at run time from the environment.

body

{ "contentType": "application/json", "data": { "name": "Rufus", "status": "available" } }

data matches the content type:

• application/json: an object.
• application/x-www-form-urlencoded: an object of fields.
• text/plain: a raw string.

auth

Three auth types:

{ "type": "bearer", "token": "{{apiKey}}" }

{ "type": "apiKey", "in": "header", "name": "api_key", "value": "{{apiKey}}" }

{ "type": "custom", "ref": { "name": "petstore-auth", "exportName": "fetchToken" } }

custom points at a TypeScript function that computes auth at run time. Instance auth overrides the defaults merged in at creation time. See Auth & middlewares.

middlewares

before/after hook chains that mutate the request before it's sent and the response after it arrives. Each entry references an exported function in the API's middlewares/ folder:

"middlewares": {
  "before": [{ "name": "tracing", "exportName": "addRequestId" }],
  "after": [{ "name": "tracing", "exportName": "warnOnServerError", "enabled": false }]
}

enabled defaults to true; set it false to keep a hook in the chain but skip it. See Auth & middlewares.