Control Blocks are GA for Cloud customers! Release for On-Premise Agent customers is coming soon.
Control Blocks make it easy to control how an API behaves, with all the power you’d expect from custom code but in an easy to use drag and drop interface.
With Control Blocks, you can:
- Conditionally run different branches of logic
- Loop over items and run many steps for each item
- Run many steps in parallel
- Handle errors gracefully
To use Control Blocks, select the Control Blocks tab when adding any backend API block.
Learn more on how to use each of the different Control Blocks below.
|Condition||Conditionally run steps|
|Loop||Use a loop to iteratively run a step|
|Break||Break out of a loop when a condition is met|
|Parallel||Run multiple steps at the same time|
|Wait||Waits for a Parallel Block to complete before executing the next step|
|Try Catch||Handle an error and run other blocks if an error is encountered|
|Throw Error||Throw a custom error message|
|Variables||Set variables to be used in other blocks|
|Return||Return data from an API|
The Condition block allows you to run different sets of API blocks depending on whether or not a condition is true (like
else if, and
else statements in code). Add blocks under the if or else conditions to run when the condition is true or false, respectively. Optionally, you can add else if conditions and toggle off the else condition in the Condition block edit pane.
Access the output of the Condition block by referencing its output property (e.g.
The output of the Condition block is the output of the last block that ran. For example, if the else condition is met, then the output of the Condition block will be the output of last block in the else section.
In this example, the value of
Condition1.output is equal to the output of the Python step,
Step3, because the condition
1 > 100 is not true.
The Loop block allows you to run sets of API blocks in a loop, much like loops in code. There are 3 types of Loop blocks:
For Each Loop
The For Each loop runs the child blocks for every item in the List of items input in the Loop edit pane.
Access the current item and current loop iteration index inside any of the child blocks using the
index.value variables. Note, these variables can be renamed in the Loop edit pane.
The For loop runs the child blocks
N times, as defined by the Number of iterations input in the Loop edit pane. Access the current loop iteration index inside any of the child blocks using the
index.value variable. Note, this variable can be renamed in the Loop edit pane.
The While loop runs the child blocks while the condition field in the Loop edit pane is true. Access the current loop iteration index inside any of the child blocks using the
index.value variable. Note, this variable can be renamed in the Loop edit pane. Check out this example guide that leverages the While loop to fetch paginated data from an API.
Your loop will run forever if you don’t update the variables that the condition field references. If your condition never becomes false, you will hit Superblocks rate limits and your API will stop running. Read more about API rate limits here.
Access the output of the Loop block by referencing its
output property (e.g.,
Loop1.output). The Loop block's output is an array with an item for every iteration of the loop. Each item is equal to the output from the last child block.
In the following example, the output of this loop block is 5 items, each of which is the output of
Step3 for the iteration of the loop. It ran 5 times because
Step1.output was an array with 5 items.
|Loop type||Default variables|
Loop index variables start at 0.
Renaming Loop variables
Inside the Loop edit pane, click the variable name to open an input popover for renaming your variable. After renaming it, the variable will update across all blocks in the Loop where it is referenced.
Advanced - setting Loop variables
If you have an advanced use case that requires updating the
index values in a language block, use
index.set(YOUR_VALUE). Just like code, setting the index value with
index.set() will change the loop iteration to the index you’ve set.
The Break block allows you to break out of a loop if a condition is true. It can only be used inside a Loop block. Set the If condition in the Break block edit pane to any code that will result in breaking out of the loop if true.
The Break block has no output.
The Parallel block allows you to run sets of API blocks at the same time. This is a powerful block that unlocks the ability to parallelize work in your APIs.
There are 2 types of Parallel blocks:
A Static Parallel block is useful when you need to run a specific number of paths simultaneously, each with their own set of blocks. The number of paths for this type of parallel does not change dynamically. You can also rename paths for readability, similar to how you can rename blocks.
Static Parallel output
Access the output of the Static Parallel block by referencing its output property (e.g.,
Parallel1.output). The output of a Static Parallel block is an object with a key for each path name, whose value is the output of the last step in that path. For example:
A Dynamic Parallel block is a very powerful block type. It will run all the child blocks for every item in the List of items field, similar to a For Each Loop block. However, unlike the Loop block, the Dynamic Parallel block will run the child blocks at the same time for every item in the list, just like parallelized code.
Access the current path's item inside any of the child blocks using the
item.value variable. Note, this variable can be renamed in the Parallel block edit pane.
Dynamic Parallel output
Access the output of the Dynamic Parallel block by referencing its output property (e.g.,
Parallel1.output). The output of a Dynamic Parallel block is an array with an item for every iteration path of the parallel, whose value is equal to the output from the last child block in each path. For example:
Dynamic Parallel variables
item is the default variable name.
Waiting configuration in Parallel blocks
Under Wait for, control whether the API should wait for all paths to complete (default) or if the API should continue without waiting.
Note, changing this to wait for none of the paths means the output of the Parallel block is not guaranteed when used in downstream blocks. In this case, use the Wait block to wait for the paths of a Parallel block to complete at a later point in the API.
The Wait block allows you to wait for an upstream Parallel block’s paths to complete.
Define the Parallel block to wait on in the Wait for parallel block field in the Wait block edit pane. When the Wait block runs, the API will wait until all paths from that Parallel block have finished, if they haven't already. The Parallel block's output is now guaranteed beyond this point, so all blocks after the Wait block can reference the Parallel block's output with confidence.
The Wait block has no output.
The Try Catch block allows you to handle errors in any of the child blocks and run other blocks as a result of encountering an error (like
try...except...finally in Python). For example, if an error is encountered trying to run some error prone code, perform an action like sending an email or alert to another system, and finally perform some clean up actions.
Add blocks under the try, catch, or if enabled, finally sections. If an error is encountered running the blocks in the try section, access the error value using the
error.value variable. Note, this variable can be renamed in the Try Catch block edit pane.
Try Catch output
Access the output of the Try Catch block by referencing its output property (e.g,
TryCatch1.output). The output of the Try Catch block is the output of the last block that ran. For example, If the try section runs without hitting an error, the Try Catch output is equal to the output of the last block in the try section. If it does encounter an error in the try section, then the output is equal to the output of the last block in the catch section. If the finally section enabled, then the output is equal to the output of the last block in the finally section, regardless of whether an error was encountered or not.
Try Catch variables
error is the default variable name.
The Throw Error block allows you to throw an error in an API with a specific error message. Define the error message inside the Error to throw field. This is the text that will be accessible from the error variable. Note, you can use a Try Catch block to catch errors thrown by the Throw Error block.
The Throw Error block has no output.
The Variables block allows you to create variables whose values can be updated at any point in an API. The Variables block is useful for updating a value over time in a Loop or Condition block, or for referencing a frequently used value across an API.
Access the variable value using
.value property on the variable name (e.g.,
Variables follow lexical scoping like variables in code. As such, a variable is available to other API blocks at the same nesting level (or below), relative to where the Variables block is defined.
Updating / setting variable values
Variables are not typed so they can be updated to any value. In the example below, a variable called
nextPage is initialized to
true at the start of a backend API that is used to iterate through a paginated REST API. When a condition is met inside a While Loop further down in the API, the variable is updated to
false. This can be done with either another Variables block
or by setting the variable in code.
- Update Variable(s) with a Variables Block
- Update Variable(s) with code
Define a new Variables block in the same scope as the original Variables block, using the same variable name whose value you want to update.
.set() function call to update a variable’s value in a code block (e.g.,
myVar.set(“my new value”))
You cannot initialize a variable in code. Setting the initial value requires a Variables block.
The Return block allows you to return from an API with data you specify. Note, you can "early return" just like in code (i.e., return before the end of the API so the remaining blocks do not run). Specify what to return in the Data to return field in the Return block edit pane.
The Return block has no output, as the API execution is terminated. The response of the API will be the data specified in the Data to return field and can be referenced via