Help › Guide
Operations
Reqlyn 0.5.1 is not released yet. This help describes it ahead of release.
An operation gives saved requests typed inputs and a declared output. It sends one or more requests in order, carries values from one response into a later request, and returns only the fields its output contract names. An operation is what you publish to a server, what a route or an MCP tool runs, and what reqlyn run runs.
Operations, the layers on the rail, lists your operations in the sidebar (the plus starts one). The editor's header holds the operation's name, its owner (a team, say), its state ("Draft · revision 3 · saved on this computer"), and Save, Publish… and Test locally. On the left are its parts: Inputs, each step, Output contract, Limits of a run, Arazzo source and Test run. The one chosen is edited on the right.
A quick way to start: on a saved request under Requests, "Use in an operation" makes a new operation whose first step sends it, with an input for each placeholder.
Inputs
What the operation is called with. "Add input" gives each a name, a kind (string, text, integer, number, boolean or file) and whether it is required. A string holds at most 2,048 characters and no line break; text is long text, up to 1 MiB with line breaks and tabs, for a file's content or a long message, and is written only inside a JSON body (in Arazzo: type: string with a maxLength over 2048). An input fills the request placeholder of the same name, {{deviceId}}, wherever it is written: the address, a header or the body.
Inputs are held to their kinds, and nothing is converted: "4831" is not an integer. An input that is not declared, a required one left out, or text with control characters is refused before anything is sent. An input written into a header or a text body that holds braces is refused, so that it cannot be read as a placeholder.
A file input is a path on the computer that runs it, or, on a server, the id of an upload. Only an input fills a multipart file part; a value carried from a response never does.
Steps
"+ Add step" adds a step that sends a saved request; "From a description or collection…" opens an OpenAPI file or a Postman, Insomnia or Bruno collection, lists its operations or requests with a filter, and saves the one you choose as a request in a folder named for the file, with a step that sends it. The file is read on this computer, nothing in it is fetched, and descriptions you opened are kept to open again. For a collection, "Take every request as a step, in order" takes them all, as Postman's runner sends them, each with its scripts translated (below); add an output field, and it can be tested and saved.
Each step has a name. Later steps and the output contract refer to its response by that name.
Mappings
A mapping fills a placeholder of the step's request from an earlier step's response: "Fills" the placeholder, from a step, at a path in its response such as items.0.id. Only text, a number or a boolean can be carried; an object or a list fails the run with STEP_MAPPING. A path may also be a JSONPath query ($.items[0].id), whose first match is taken.
Repeat for each item
"Repeat for each item" sends the step once for every item of a list in an earlier step's response: "The list in" a step at a path, the placeholder each item fills, "Most items", and "At once" (how many are sent together, for a request that only reads). The step's result is the list of the answers, in the order of the items, however they completed.
Read page by page
"Read page by page" follows a paged list until its end: By cursor (where the next cursor is in a page, and the placeholder it fills), By offset and By page number (the placeholder, the first value and the page size), or By link (where the next link is in a page, or the response's Link header). "Items at" says where a page's items are. The step's result is every page's items as one list, bounded by "Pages" and "Items". A next link is followed only to the scheme, host and port the page was asked at; a link holding its own user name or password is refused.
Join on a key
A join puts together what two steps received. "Take one item" picks one item of an earlier step's list whose key equals a value ("If no item matches": fail the run or go on with nothing; "If several match": fail the run or take the first). "Pair each item of that step's list" pairs two whole lists by a key in each. Keys are compared exactly; no near-match is made.
Conditions
"Add a condition" makes a step run only when every comparison holds, at most 16 of them, each an input or a path in an earlier response compared with a literal: equals, is not, is more than, is less than, is there, is not there. Values of different kinds are never converted to compare them, and whole numbers are compared exactly. A step that did not run gives null.
Succeeds when
A step's "Succeeds when" part holds its success criteria, as an Arazzo document's successCriteria are. Without any, its response's status decides. "Add a criterion" adds one; each looks at the status, a header by its name, the body by a path such as items.0.id (empty for all of it), an input, an earlier step's result by a path, the method or the address, and:
- compares it with a value (equals, is not, is less than, is at most, is more than, is at least), typed as text, a number,
true,falseornull; text in double quotes stays text, so"200"is not the number; - matches a pattern, a regular expression;
- JSONPath selects something in it;
- XPath holds of it, for an XML response.
Every criterion has to hold, or the step has failed. One that looks at the status decides on its own, whatever the status is. Nothing is converted to compare. A criterion the form cannot show (one joined to another by ||, or by !, or with a value on its left) is shown as written, "set in the Arazzo source", kept as it is when the operation is saved, and edited in the source; it can be removed here.
If it fails
A step's "If it fails" part says what a failure does:
- The run fails, naming the step and why, or the run goes on: the step is optional, and the run's result is then partial, each field it would have given null. A time limit applies to an optional step.
- Tried again: Never, Once or Twice, after no answer or a 429, 502, 503 or 504, for a request that only reads (GET, HEAD, OPTIONS). A request that writes is sent once and never repeated.
- Waits: how many seconds the step waits for each response, up to 30 (0 for the usual 30). A request stopped for want of an answer fails with STEP_TIMEOUT: whether the API acted on it cannot be known.
- Error rules: "Add an error rule" says when a successful status still means a failure, such as
successequalsfalse, with "Path of the API's own message, such as error.message" to quote. The run then fails with STEP_REPORTED and that message.
When it succeeds, when it fails
A step's actions, as an Arazzo document's onSuccess and onFailure are. "Add an action" adds one, with a name, and what it does:
- End the run: with its output after a success, failed after a failure.
- Go to a step, earlier or later, chosen among the operation's steps.
- Try again, on failure only: at most so many times (to 10), waiting so many seconds first (to 300). A retry that also runs another step first is set in the Arazzo source and shown here as written.
Each action has criteria, as "Succeeds when" has; it is taken only when every one holds, and with none, whenever it is reached. The first action that applies is taken, and a retry whose tries are spent is passed over. With none taken, a step that succeeded goes on to the next, and one that failed is as "If it fails" says. A request that writes is never sent again. Saving an operation refuses an action with no name, more than 16 a list, a retry on success, or one that goes to a step that is not there.
Set in the Arazzo source and shown here as written: a step that waits for a value ("Asked again until state is done: every 2 s, at most 30 times"), a request that undoes the step, and a request that reads what it writes to. See Testing and recovery.
The canvas
"Canvas", at the end of the operation's parts, draws the operation as it stands in the editor, left to right from Start to End: each step a block headed by its method and its name, with what it sends and what it does besides (a condition, a loop, pages, a script and so on), joined to the next by a wire. Each action is an arc to the step it goes to, or to the end: over the blocks going on, under them going back, a small loop for a retry; solid on success, dashed on failure, with what it says on it. A workflow a step calls is a region around its steps. Choose a block to open its step. While the canvas is open, the sidebar holds the operation's parts and what can be added.
Test locally from the canvas: each block says how its step ended, its last status and its time, a failed one outlined in red. Choose a wire between two blocks and the drawer under the canvas shows what passed along it, field by field with each value's kind (a field the operation masks says "masked"), what the next step takes from it, and the run's timing; "Open the test run" opens the run's own record. A step whose request writes says "writes"; and when this computer is linked to a server where the operation is published, each step says its drift there, as the latest version's runs have shown it.
The canvas also builds the operation. Drag a saved request from the sidebar into the room between two blocks, and a step that sends it is added there. "Open a description or collection…" lists that file's operations in the sidebar; dragging one saves it as a request first. Drag a block into another room to move its step, or anywhere else on the canvas to put it there: a block put somewhere stays there, the others in the row, its wires curving to it, and "Arrange in a row" puts them all back. A request let go away from the rooms is a step put where it was let go. Where each block is is the operation's, saved with it, in its Arazzo source as x-reqlyn-place, and the web client's canvas draws it the same. To add an action, drag from a block's right-hand port onto the step it should go to (onto its own block, to try it again when it fails; onto End, to end the run); the step's form opens at its actions to name it and say when it is taken. Right-click a block for "Run only if…", "Repeat for each item…" and an action when it succeeds or fails, each opening the step's form at that part. The changes are the editor's, saved with Save as any other.
All of it works from the keyboard. Opening the canvas puts the keyboard on its blocks: Left and Right move between them, Enter opens a step, Alt+Left and Alt+Right move a step one place, Shift with an arrow moves its block on the canvas, and W shows the wire into the block in the drawer. Shift+Tab reaches the requests in the sidebar; Enter on one adds a step after the block you were last on. Screen readers announce each step, what it sends, how the last test left it and its marks.
Scripts
A step may run JavaScript before its request is sent and after its response comes back: to change the request, check the response, and pass values to later steps. Its "Scripts" part, at the end of the step's editor, opens with "Add scripts": a field for each script, the names its scripts set, and what a script is given beside them. A collection from Postman, Insomnia or Bruno taken as steps brings its scripts translated. Everything about them is in Scripts.
Output contract
The fields the operation returns, each with a name, a kind (string, integer, number or boolean), the step it comes from and the "Path in the response". A field can be a list, and "May be null" allows null, and allows the response to leave the field out where its object is: many APIs omit an empty or zero field. A run is held to its contract: a field that is missing, null where it may not be, or of another kind fails the run (OUTPUT_MISSING, OUTPUT_NULL, OUTPUT_KIND), naming the field and the place. Nothing a response holds is returned unless the contract names it.
Limits of a run
The most one run may do. A run that reaches a limit is stopped, whatever its steps say about going on (RUN_LIMIT).
- Sends at most N requests, 1 to 1,000 (1,000 unless you lower it). Every page, every item of a loop and every further attempt is one. Beside it, the most requests a run of the operation as edited can send, worked out from its steps' loops, pages and retries: a ceiling, not a guess.
- Takes at most N seconds, 1 to 300 (300 unless you lower it). A request still waiting when the time is up is stopped, and the run with it.
- Only reads: your word that nothing the operation sends changes anything, whatever method a step uses. A server schedules, and offers as an MCP tool without a grant, only an operation that only reads, declared so or with every step a GET. The publication review lists each step that does not send a GET as not verified.
- Never keeps the fields: names of fields whose values are masked, at any depth and whatever their case, in any body a run keeps.
Arazzo source
Every saved operation is also an Arazzo 1.1 document, written when it is saved, with an OpenAPI description for each origin its requests go to. This part shows it. Edited, "Save source" saves the document as written and the operation becomes what it compiles to; a source that does not compile is not saved, and each problem is shown at its place. See Arazzo workflows.
A step owns a copy of its request. Editing the saved request afterwards changes no operation: the editor names the requests changed since, and Save takes them.
Testing
"Test locally" runs the operation from this computer, as it is in the editor, with the inputs given in the Test run part. The Test run part then shows how the run ended ("The last run returned its output", "… returned part of its output", "… failed"), each step with its requests, attempts and time, and the output. Testing, breakpoints, examples, cases and previews are in Testing and recovery.
From the command line:
reqlyn list
reqlyn run "Device overview" --input '{"deviceId": 4831}'
Lint rules
"RULE · The workspace's rules" lists what the workspace's lint rules find in the operation as it was last saved: its name, description and owner, each request its steps send, and each OpenAPI or AsyncAPI description of its Arazzo source. They are what the publication review holds it to, and an error among them stops publishing. Linked to a server, the rules are the workspace's ruleset as its server holds it; otherwise, or until the workspace sets one, Reqlyn's own rules, none above a warning. Each finding gives its rule, its place and, for one in a step or the request a step sends, "Open the step". The list is read again when the operation is saved and when the part is chosen. Lint rules for a description lists the rules, and Using a server how a workspace sets its own.
Publishing
"Publish…" sends the operation to the linked server as a draft and shows the server's review before anything is published. See Using a server.
Help for Reqlyn 0.5.1. All help topics