Flows

A flow connects blocks on a canvas, as in Postman Flows. Data leaves a block’s outputs on the right and travels along connections into the inputs of other blocks on the left. Flows chain saved requests, reshape their responses with FQL, branch, loop and collect results, without writing a script.

Click + in the Flows section of the sidebar, or run New flow from the command palette. As in Postman, flows are kept apart from collections: a flow can send requests saved in any collection. It opens in its own tab, and its row in the sidebar opens, renames, duplicates or deletes it.

The canvas

Selecting one block opens its settings on the right, with what it received and sent in the last run. An HTTP Request block goes by the name of its request unless it has its own title, and dims the variables its collection or the active environment already fill. The settings panel and the run log can be resized by dragging their edges. Shortcuts can be changed in the keyboard settings.

Running

Click Run or press Ctrl/Cmd Enter. The flow runs as it is in the editor, saved or not, with the environment selected in the tab bar. Blocks show a spinner while they work, a check and their run count when they ran, and their error when they failed. HTTP Request blocks show the status they received, in red when the request failed and went out of Fail, and the toolbar counts failed requests. Connections that carried data are colored, red when they carried a failure, and Display blocks show what they received last.

The run log lists every block’s run with what it sent, numbering the runs of blocks that ran more than once, as in a loop. Choosing an entry selects its block and shows that run in the settings panel; Selected block only keeps to the selected block’s entries.

A run sends requests like their tabs do: their collection’s variables, the active environment, session values set by scripts, the cookie jar and the collection’s and request’s scripts all apply. A run stops after 100,000 block runs, which ends a loop that never does.

How data moves

• A block runs when every connected input has received a value, and runs again whenever one of them receives another, with the latest value of the others.
• When a run starts, Start blocks send their input. Blocks that need no input to work, such as String, Evaluate or HTTP Request, run then as well when none of their inputs are connected.
• An HTTP Request block with a connected Send input waits for it, which orders requests that share no data: connect Login’s Success to the next request’s Send.
• For sends each item of a list and Repeat each index up to its count, one at a time. Each item travels as far as it can before the next starts. A Collect block after the loop sends the results, in order, once the loop ends; an empty loop collects an empty list. Adding a loop adds its Collect.
• A block only combines values of the same loop iteration. A value from outside the loop, such as a token, combines with every iteration.
• A connection may lead back to an earlier block, for example to fetch pages until there is no next page. Values of one pass through such a cycle are combined only with each other.
• When a block fails, the run log shows why, and the rest of the flow carries on.

Blocks

An HTTP Request block sends:

{
  "body": {"parsed": "JSON, or the text"},
  "http": {"status": 200, "headers": {"content-type": "application/json"}, "time": 41.2},
  "tests": [{"name": "Status is 200", "passed": true, "error": null}],
  "binary": false
}

Header names are lowercase. A body that is not UTF-8 is Base64 with "binary": true. A request that could not be sent goes out of Fail as {"error": "…"}.

FQL

Evaluate, If and Condition blocks use FQL, the query language of Postman Flows, which is JSONata. Their variables are fields of the input, so an expression reads them by name:

value1.http.status = 200
response.body.users[active].{ "id": id, "name": $uppercase(name) }
$sum(order.items.(price * quantity))

Inside a predicate a bare name reads the item, so compare with a variable through $$ or bind it first: users[name = $$.search].

FQL adds Postman’s functions to JSONata’s, such as $jsonParse, $json, $uuid, $partition and date arithmetic like $datePlus and $diffDate. Lambdas can be written fn($x) { … } as well as function($x) { … }. Selecting a block with an expression shows its result for the inputs of the last run as you type.

From the CLI

request-eagle-cli creates, edits and runs flows without the app:

request-eagle-cli call '{"command":"flows.blocks"}'
request-eagle-cli call '{"command":"flows.list"}'
request-eagle-cli call '{"command":"flows.run","path":"/absolute/path/Checkout.toml","input":{"user":"ada"}}'
request-eagle-cli call '{"command":"fql.evaluate","expression":"$sum(items.price)","input":{"items":[{"price":2}]}}'

See the CLI guide for the rest.

The file

A flow is a TOML file in ~/.request-eagle/flows, named after the flow when it was created. Renaming a flow keeps its file. Flows that version 0.1.22 saved in collections move to this folder when a newer version starts.

id = "6c1d…"
name = "Checkout"
schema_version = 1

[[flow.blocks]]
id = "b1"
type = "start"
x = 0.0
y = 0.0

[[flow.blocks]]
id = "b2"
type = "http_request"
x = 320.0
y = 0.0
request = "id of the saved request"

[[flow.connections]]
from = "b1"
output = "data"
to = "b2"
input = "send"

HTTP Request blocks refer to requests by ID, so moving or renaming a request keeps its blocks working.