Help › Guide
Arazzo workflows
Reqlyn 0.5.1 is not released yet. This help describes it ahead of release.
Arazzo is the OpenAPI Initiative's format for workflows over APIs: steps that call operations of OpenAPI (and AsyncAPI) descriptions, with inputs, outputs, criteria and actions. In Reqlyn an operation's source of truth is an Arazzo 1.1 document. Reqlyn compiles it to the operation it runs, so the desktop, the command line, the server, routes and MCP tools all run what the document says.
Working with documents
| Command | Does |
|---|---|
reqlyn arazzo check <file> |
Reads an Arazzo 1.0 or 1.1 document, in YAML or JSON, and says what is wrong with it, each problem at its place. Runs nothing. |
reqlyn arazzo compile <file> [--workflow <id>] |
Prints the operation and requests Reqlyn would run. What Reqlyn cannot run is named at its place, and it ends with 1. |
reqlyn arazzo run <file> [--workflow <id>] --input <json> |
Compiles and runs the workflow on this computer, with the chosen environment's variables. Stores nothing. |
reqlyn arazzo save <file> |
Compiles the document and stores it as a new operation, its source the document and its descriptions. A <name>.cases.yaml beside it is kept as its regression cases. |
reqlyn arazzo export <operation> [--out <folder>] |
Writes a stored operation as an Arazzo document, an OpenAPI description for each origin it calls, an AsyncAPI description for each server it sends or hears messages on, and its cases. A file already there is not overwritten. |
In the desktop, every saved operation has an "Arazzo source" part that shows its document and descriptions as last saved. Edit them and press "Save source": the operation becomes what the source compiles to, or, if it does not compile, nothing is saved and each problem is shown at its place.
Where descriptions come from
A document's sourceDescriptions are read from files beside it, by their url (./inventory.openapi.yaml). Nothing is fetched from an address. Another Arazzo document can be a source too, and its workflows are called as the document's own.
Servers, variables and credentials
A step's request goes to its description's server. A server written with a variable, such as url: "{inventory}", becomes the variable {{inventory}}, filled from the environment the workflow runs in: on this computer, the Variables tab of the chosen environment; on a server, the environment the version is activated in. On this computer, a server variable that no variable of that name sets takes the description's default (an empty one is no default), in a run as in a write preview's reads first and an undo, and --var <name>=<value> on reqlyn run or reqlyn arazzo run sets one for that run over both. A server never takes a default: an environment binds what a version names, and activation checks it.
An OpenAPI operation names the credential it is sent with by x-reqlyn-credential: <name>: a credential of that name under Connections on this computer, or bound in the environment on a server. A secret never goes in the document, and a credential header written as a literal is refused. A document run from a file never uses a secret variable.
An example
The fixtures' inventory and compliance APIs, with descriptions in fixtures/arazzo/:
arazzo: 1.1.0
info: { title: Device overview, version: 1.0.0 }
sourceDescriptions:
- { name: inventory, type: openapi, url: ./inventory.openapi.yaml }
- { name: compliance, type: openapi, url: ./compliance.openapi.yaml }
workflows:
- workflowId: deviceOverview
inputs:
type: object
required: [deviceId]
properties:
deviceId: { type: integer }
steps:
- stepId: device
operationId: $sourceDescriptions.inventory.getDevice
parameters:
- { name: deviceId, in: path, value: $inputs.deviceId }
successCriteria:
- condition: $statusCode == 200
outputs:
id: $response.body#/id
hostname: $response.body#/hostname
- stepId: compliance
operationPath: '{$sourceDescriptions.compliance.url}#/paths/~1compliance~1devices~1{id}~1status/get'
parameters:
- { name: id, in: path, value: $steps.device.outputs.id }
outputs:
compliant: $response.body#/compliant
outputs:
hostname: $steps.device.outputs.hostname
compliant: $steps.compliance.outputs.compliant
Each output is typed by what the description documents at that place, and the workflow's outputs become the operation's output contract. The tutorial Arazzo workflows runs it step by step.
What Reqlyn runs
Every construct of Arazzo 1.0 and 1.1 is read, kept when the document is written back, and checked. Compiling takes everything below; anything else is refused at its path, never silently left out.
Steps and their requests
- A step's operation by
operationId(plain, or$sourceDescriptions.<name>.<id>) or by anoperationPathpointer. - Parameters in the path, query and header: literals,
$inputs.<name>,$steps.<id>.outputs.<name>, and{$…}inside text. A workflow's ownparameters, and parameters from the components by reference. - Request bodies: a JSON payload with expressions (typed by the input or the description),
replacementsput at their targets, a JSON payload written as text with{$expression}s in it, a form, a multipart body (a file part filled by a file input, an input oftype: string, format: binary), or text. timeoutup to 30,000 milliseconds, anddependsOn.- Inputs: an object schema of strings, integers, numbers, booleans and files.
Outputs and selectors
- A step's outputs from
$response.body#/<pointer>,$response.header.<name>and$message.payloadand$message.header.<name>for a message. - Selector objects of type
jsonpointerandjsonpath(RFC 9535) in a step's outputs, a parameter's value, a payload's values and a workflow's outputs. A JSONPath query that selects one value gives the first it selects; a list output gives each. - Selector objects of type
xpath, with XPath 3.1, over an XML response. The step keeps its response as XML; each selector gives text, or a list when it selects several. A document type or entity in the XML is refused, and XPath reads no file or network.
Criteria
successCriteria, and an action's criteria, as:
- simple conditions:
&&,||,!, parentheses,==,!=,<,<=,>,>=, over$statusCode,$method,$url,$response.header.<name>,$response.bodyand pointers into it,$request.header,.query,.pathand.body(what the step itself writes),$inputs.<name>and$steps.<id>.outputs.<name>, each followed by[<index>]or.<name>; - regex criteria on a context, matched in linear time;
- jsonpath criteria, holding when the query selects something;
- xpath criteria, holding by XPath's effective boolean value.
Nothing is converted to compare. A criterion that looks at the status decides the step's success whatever the status. A criterion has at most 64 parts, 8 deep.
Actions
onSuccess and onFailure actions, the workflow's successActions and failureActions after the step's own, and actions from the components:
end, anywhere;gotoa step, earlier or later, or a workflow with itsparameters;retrywithretryAfter(up to 300 seconds),retryLimit(up to 10) and astepIdorworkflowIdtaken first.
The first action whose criteria hold is taken; a retry that is spent is passed over. A request that writes is never retried. A run that loops is bounded by its limits and by 1,000 steps taken.
Workflows calling workflows
- A step with
workflowIdruns that workflow's steps in its place, named<step>.<its step>, its inputs given by the step's parameters. Its outputs are the step's. dependsOnanother workflow runs that workflow first, once;$workflows.<id>.outputs.<name>reads its outputs.- A workflow of another Arazzo document is
$sourceDescriptions.<name>.<workflowId>. - A workflow that would run itself, or calls more than 8 deep, is refused.
Messages: AsyncAPI steps
An AsyncAPI 2.6 or 3.0 description can be a source. A step that names an AsyncAPI operation (by operationId or operationPath) or a channel (channelPath) sends or receives a message instead of making an HTTP request, with action and, for a receive, correlationId. Its outputs and criteria read $message.payload and $message.header.<name>.
| Protocol | Server's protocol |
Address | Sends | Receives |
|---|---|---|---|---|
| WebSocket | ws, wss |
the channel's address | a text message | a message heard on the same socket |
| Server-sent events | sse, sses |
the channel's address | — | an event of the stream |
| HTTP bindings | http, https |
the channel's address | a request with the payload as its body | a request whose answer is the message |
| Kafka | kafka, kafka-secure |
kafka://<broker>/<topic> |
a record to the topic's first partition, keyed by the step's header key, which is not sent as a header; not compressed |
a record of any partition since the run began, its key as the header key, compressed or not (gzip, snappy, zstd, lz4) |
| MQTT | mqtt, secure-mqtt |
mqtt://<broker>/<topic>, mqtts:// over TLS |
published at QoS 1, or the QoS and retain the operation's bindings.mqtt says |
subscribed before the run's first step, at that QoS |
| AMQP 0-9-1 | amqp, amqps |
amqp://<broker>/<queue or routing key>, with exchange and vhost from the channel's binding |
to a queue, or a routing key on an exchange | from a queue, or a queue of the run's own bound to the exchange; a named queue has to be on the broker, and one that is not is refused by its name, Reqlyn making none |
| AMQP 1.0 | amqp1, amqp1s |
amqp1://<broker>/<address> |
by a sender, its headers as application properties | by a receiver; its headers are the application properties, the standard properties (message_id, correlation_id, subject, to, reply_to, content_type, group_id) and the message annotations |
A channel a step receives on is listened to from the run's start when the inputs alone fill its address, so a message sent in answer to an earlier step is not missed. A receive takes the first message, heard since the run began, that its correlation id names, within the step's timeout; at most 1,000 messages are kept for a channel until a step takes one. Channels stay open until the run ends.
On a server or a private agent, a message step is held to the allowed destinations as a request is: a WebSocket by its HTTP counterpart's origin (http://host:port for ws://host:port), a broker by its own (kafka://host:port), and each to the addresses the guard allows. WebSocket, AMQP and MQTT steps go through the proxy or the SSH bastion set under Connections, by their tunnel, and server-sent events and HTTP bindings as any request does. Kafka steps go through the proxy or the bastion, by a bridge of Reqlyn's own on this computer, which through the bastion opens only the first broker's port. An AsyncAPI server names the credential it is reached with by x-reqlyn-credential. Kafka takes a basic credential as SASL PLAIN; AMQP 1.0 takes it as SASL PLAIN, and ANONYMOUS without one. TLS is the transport's own, with the same certificate authorities as any request; MQTT's is the platform's TLS (OpenSSL on Linux), and AMQP 0-9-1's is its client's own; both trust the platform's authorities and those added under Connections. A server's x-reqlyn-client-certificate, in a source this computer keeps, names the client certificate they present; its key has to be PKCS#8.
A broker is an origin a server must be allowed to reach, such as kafka://broker:9092 in REQLYN_ALLOWED_DESTINATIONS.
An MQTT server whose protocolVersion is 5 (or 5.0) is spoken in MQTT 5: a send's headers go as user properties, content-type as the message's content type, and a message heard has its user properties and content type as headers, so a correlation id or an output may be read from one. Otherwise MQTT 3.1.1, which carries no headers.
A Kafka server's credential is named by x-reqlyn-credential on the server. A basic credential signs in by SASL PLAIN, or by SCRAM-SHA-256 or SCRAM-SHA-512 when the server's security names a scheme of type scramSha256 or scramSha512; a bearer token, or an OAuth client's token, signs in by OAUTHBEARER.
Reqlyn's own fields
Where Arazzo has no word for what a step does, Reqlyn writes an x-reqlyn-* field:
| Field | On | Means |
|---|---|---|
x-reqlyn-when |
a step | The step's condition: it runs only when its comparisons hold |
x-reqlyn-policy |
a step | Optional, retries, when a success is an error, waiting for a value (until), a callback |
x-reqlyn-each |
a step | Repeat the step for each item of a list |
x-reqlyn-pages |
a step | Read a paged list to its end |
x-reqlyn-join |
a step | Join two steps' results on a key |
x-reqlyn-bare |
a step | Places in a payload where a carried value is written as it is, not quoted |
x-reqlyn-undo |
a step | The request that undoes the step, sent only when a person asks |
x-reqlyn-before, x-reqlyn-at |
a step | The request that reads what the step writes to, for a write preview, and where the record is in its answer |
x-reqlyn-environment |
a step | Variables of this computer the step's request names outside its origin |
x-reqlyn-place |
a step | Where its block was put on the canvas, { x, y } in the canvas's pixels; none, in the row. Only drawing reads it. An older Reqlyn says it does not know it |
x-reqlyn-script |
a step | Its JavaScript: before its request is sent, after its response, and the names the after script sets, which later steps' requests hold as {{name}}. Not on a message step. Runs on the desktop, the command line, a server and a private agent |
x-reqlyn-action |
a failure action | A plain retry of the step that is an action of its own, taken on any failure, and not the step's retries (which a first plain retry is otherwise read as) |
x-reqlyn-owner, x-reqlyn-list-outputs |
a workflow | Its owner; which outputs are lists |
x-reqlyn-credential |
an OpenAPI operation, an AsyncAPI server | The credential's name |
x-reqlyn-client-certificate |
an OpenAPI operation, an AsyncAPI server | A client certificate's name, used only by a source this computer keeps; a server refuses it |
How a version is hosted (limits, fields never kept, reading only, keeping bodies, routes) is not in the document: it belongs to the deployment manifest.
Not run yet
- An XPath selector over an earlier step's output, or over a pointer into a body: an XML step's outputs are text, not XML.
- gRPC: it is not an Arazzo source. An operation's step calls it, streams included, from a saved request (Requests).
Help for Reqlyn 0.5.1. All help topics