Help › Tutorials
Tutorial 2: Arazzo workflows
Reqlyn 0.5.1 is not released yet. This help describes it ahead of release.
In Reqlyn an operation's source is an Arazzo document: a workflow of steps over OpenAPI (and AsyncAPI) descriptions. This tutorial works with documents directly, from the command line. You will check, compile and run a workflow; add success criteria and a retry action; let a step be optional; run a WebSocket message workflow; then store the document as an operation, keep a case, and export it.
Every command below was run against the fixtures as written. It takes about twenty minutes.
Before you start
- The fixture APIs are running (
cargo run -p reqlyn-fixtures). - You have done tutorial 1, or at least step 1 of it: the variable
inventoryset tohttp://127.0.0.1:8787. - Copy the repository's
fixtures/arazzo/folder somewhere to work in, and open a terminal there. It holdsdevice-overview.arazzo.yaml,inventory.openapi.yamlandcompliance.openapi.yaml.
1. Export what you built
If you did tutorial 1, see it as Arazzo first:
reqlyn arazzo export "Device overview" --out exported
writes device-overview.arazzo.yaml, an OpenAPI description of the inventory as the workflow uses it, and device-overview.cases.yaml with the case you kept. Open the document: each step names an operationId, its parameters say where each value comes from ($inputs.deviceId, $steps.device.outputs.id), and the optional step is written as x-reqlyn-policy: { optional: true }.
2. Check, compile and run a document
reqlyn arazzo check device-overview.arazzo.yaml
Valid, and each of its 1 workflow(s) compiles. Nothing was run.
check reads the document and its descriptions and says what is wrong, at its place. compile prints what Reqlyn would run, the requests and the operation, still sending nothing:
reqlyn arazzo compile device-overview.arazzo.yaml
Note that the compliance request goes to {{compliance}}: the description's server is written url: "{compliance}", and a server variable becomes a variable of the environment. You did not set compliance, so it takes the description's default, http://127.0.0.1:8787. A variable set in the environment is taken over the default, and --var compliance=… on the command line over both, for that run.
Now run it:
reqlyn arazzo run device-overview.arazzo.yaml --input '{"deviceId": 4831}'
{
"compliant": false,
"findings": 2,
"hostname": "pe01.pitb02-pa",
"noted": "POST",
"role": "PE"
}
Each output's type comes from what the description documents at that place.
3. Criteria and a retry
Make a copy, device-check.arazzo.yaml, to change. First a description for one more endpoint. The fixtures' /flaky/{key} answers 503 twice for each key, and then 200 with how many requests it took. Save this as health.openapi.yaml:
openapi: 3.1.0
info: { title: Health (fixture), version: "1" }
servers:
- url: "{inventory}"
paths:
/flaky/{key}:
get:
operationId: getHealth
parameters:
- { name: key, in: path, required: true, schema: { type: string } }
responses:
"200":
description: Up, and how many requests it took
content:
application/json:
schema:
type: object
properties:
attempt: { type: integer }
"503":
description: Not up yet
Then write device-check.arazzo.yaml:
arazzo: 1.1.0
info: { title: Device check, version: 1.0.0 }
sourceDescriptions:
- { name: inventory, type: openapi, url: ./inventory.openapi.yaml }
- { name: compliance, type: openapi, url: ./compliance.openapi.yaml }
- { name: health, type: openapi, url: ./health.openapi.yaml }
workflows:
- workflowId: deviceCheck
summary: Device check
inputs:
type: object
required: [deviceId, check]
properties:
deviceId: { type: integer }
check: { type: string }
steps:
- stepId: health
operationId: $sourceDescriptions.health.getHealth
parameters:
- { name: key, in: path, value: $inputs.check }
successCriteria:
- condition: $statusCode == 200
onFailure:
- name: notUpYet
type: retry
retryAfter: 1
retryLimit: 3
criteria:
- condition: $statusCode == 503
outputs:
attempt: $response.body#/attempt
- stepId: device
operationId: $sourceDescriptions.inventory.getDevice
parameters:
- { name: deviceId, in: path, value: $inputs.deviceId }
successCriteria:
- condition: $statusCode == 200
- context: $response.body#/hostname
condition: '^[a-z]+[0-9]+\.'
type: regex
outputs:
id: $response.body#/id
hostname: $response.body#/hostname
role: $response.body#/role
- stepId: compliance
operationId: $sourceDescriptions.compliance.getComplianceStatus
parameters:
- { name: id, in: path, value: $steps.device.outputs.id }
successCriteria:
- condition: $statusCode == 200
outputs:
compliant: $response.body#/compliant
findings: $response.body#/findings
outputs:
attempts: $steps.health.outputs.attempt
hostname: $steps.device.outputs.hostname
role: $steps.device.outputs.role
compliant: $steps.compliance.outputs.compliant
findings: $steps.compliance.outputs.findings
- The
healthstep'sonFailureaction retries it a second later when the answer is 503, at most three times. - The
devicestep's criteria hold only for a 200 whose host name matches the regular expression.
Run it with a check key the fixture has not seen:
reqlyn arazzo run device-check.arazzo.yaml --input '{"deviceId": 4831, "check": "first"}'
It takes about two seconds, and gives "attempts": 3 beside the device: two 503s, each retried after a second, then the answer. Run it again with the same key and it is 4, with no retry. (A retry is never made of a request that writes.)
4. An optional step
Device 4840 is not known to the compliance API:
reqlyn arazzo run device-check.arazzo.yaml --input '{"deviceId": 4840, "check": "second"}'
Step "compliance": the server answered 404, which is not success, so there is no output.
To have the host name anyway, let the run go on without the step. Add to the compliance step:
x-reqlyn-policy:
optional: true
and run again. Reqlyn now refuses to compile it:
workflows[0]: The output field "compliant" comes from the step "compliance", which the run may go on without, so it has to allow null.
An output takes its type from the description, and the description says compliant is always a boolean. In your copy of compliance.openapi.yaml, allow null for the two fields:
compliant: { type: [boolean, "null"] }
findings: { type: [integer, "null"] }
Now 4840 gives its host name and role, "compliant": null and "findings": null, says it went on without the compliance step, and ends with 3: a partial result.
5. A message over a WebSocket
A step can send or receive a message on a channel of an AsyncAPI description instead of making an HTTP request. The fixtures echo on a WebSocket at ws://127.0.0.1:8793: they greet a new connection with {"connected": …} and answer each message with {"echo": "<what was said>"}. Save echo.asyncapi.yaml:
asyncapi: 3.0.0
info: { title: Fixture echo, version: "1" }
servers:
echo: { host: 127.0.0.1:8793, protocol: ws }
channels:
echo:
address: /
servers: [{ $ref: "#/servers/echo" }]
messages:
said:
payload:
type: object
properties:
echo: { type: string }
connected: { type: boolean }
operations:
say: { action: receive, channel: { $ref: "#/channels/echo" } }
hear: { action: send, channel: { $ref: "#/channels/echo" } }
An AsyncAPI operation is written from the application's side: the echo receives what the workflow says, and sends what the workflow hears. Then echo.arazzo.yaml:
arazzo: 1.1.0
info: { title: Echo, version: 1.0.0 }
sourceDescriptions:
- { name: echo, type: asyncapi, url: ./echo.asyncapi.yaml }
workflows:
- workflowId: echo
inputs:
type: object
required: [line]
properties:
line: { type: string }
steps:
- stepId: greeted
operationId: $sourceDescriptions.echo.hear
successCriteria:
- condition: $message.payload#/connected == true
- stepId: say
operationId: $sourceDescriptions.echo.say
requestBody:
contentType: application/json
payload:
said: $inputs.line
- stepId: echoed
operationId: $sourceDescriptions.echo.hear
timeout: 5000
outputs:
echo: $message.payload#/echo
outputs:
echo: $steps.echoed.outputs.echo
reqlyn arazzo run echo.arazzo.yaml --input '{"line": "hello from Reqlyn"}'
{
"echo": "{\n \"said\": \"hello from Reqlyn\"\n}"
}
The channel is listened to from the run's start, so the greeting is not missed; it stays open until the run ends. Kafka, MQTT and AMQP channels are written the same way, with their own servers: see Arazzo workflows.
6. Store it, keep a case, export it
reqlyn arazzo save device-check.arazzo.yaml
reqlyn list
reqlyn run "Device check" --input '{"deviceId": 4832, "check": "third"}' --keep-case pe02
reqlyn test "Device check"
reqlyn arazzo export "Device check" --out check-export
savecompiles the document and stores it as an operation whose source is the document and its descriptions. It shows in the desktop's Operations too, with its source in the Arazzo source part.run --keep-caseruns it and keeps the run as the casepe02;testreplays it with nothing sent:1 of 1 cases hold.exportwrites it back: the document, its descriptions anddevice-check.cases.yaml. That folder is what you keep in a repository, and what tutorial 4 checks in CI.
What you did
check,compileandrunworked on a document with nothing stored.- Success criteria (a status and a regular expression) and a retry action shaped what counts as success and what happens after a failure.
- An optional step needed its outputs to allow null, which the description says.
- A workflow sent and heard messages on a WebSocket channel.
- A document became a stored operation with a case, and was exported for version control.
Everything Reqlyn runs of Arazzo, and what it does not run yet, is in the guide.
Help for Reqlyn 0.5.1. All help topics