Backend APIs
Connect your Database, APIs, and write business logic in JavaScript or Python. Reference previous Steps and Components to make your application dynamic
What are Superblocks APIs?
Superblocks APIs are the business logic layer of your application, built on top of your data sources. These backend APIs run server side (on Superblocks servers if you're using the cloud version or on your own infrastructure if you're using the OPA), and send a response back to your components in the frontend user interface. This separation of the application into a frontend and backend is a core concept when working with APIs. For example, a backend API cannot update a frontend component's state directly. Instead, the component reacts to the response from the API.
In the example below, we query the Zendesk GET Ticket API, then get the associated customer orders from Postgres, get the order shipping data from Snowflake, and merge and transform the Postgres/Snowflake output using Python.
Working with Superblocks APIs
Referencing Component Data
You can use {{}}
in SQL / REST / GraphQL steps to reference components in the Canvas.
To reference other components you can write:
{{Input1.text}} //The value of the input
{{Table1.selectedRow.city}} //The selected row JSON object from the Table
{{Chart1.selectedData}} //The selected data point JSON object from the Chart
{{Dropdown1.selectedOptionValue}} //The option selected in the Dropdown
info
Tip The curly braces evaluate to JavaScript and are not needed in JavaScript or Python steps
Referencing a previous Step in the API Builder
You can also reference the output from previous steps in an API.
{{Step1.output}} //The JSON output object from the Step1
{{Step1.output[0]}} //The object at index 0 of the array
{{Step1.output[0].id}}} //The id property of the 0th index
Referencing another API output in the API Builder
The output of another API can be referenced within an API step. Note that the referenced API must have run before its value is called for. In the example below the response from API1
is referenced in API2
:
Using an API Response to fill Components
The response of an API is the result of the final step in the sequence. You can use the response in the Table Data, Chart Data, Dropdown Data, Grid Data and other related data entry fields.
{{API1.response}} // Reference the response of an API in frontend bindings
In the following example, a frontend Table component is populated with data from a Backend API called getOrders
. Note that the API response object must be wrapped in frontend bindings:
Running an API on Component Event Handler
Frontend components have event handlers that can be used to respond to user events. Among other things, they can be used to execute an API based when an event happens. In the following example, the event handler onTextChanged for Inputs triggers a Run API Action Type that runs a backend API called API1
:
API trigger block
With the help of the API Trigger block, the settings can be made that decide when an API is executed and who is allowed to execute this API.
API Triggers
Each backend API has a trigger block that lists which API Triggers cause the API to run.
Run on page load
Whether the API also Runs on Page Load event can be set directly in the block:
Always
means the API will be executed on every Page Load eventNever
means the API will never be executed when a Page Load event occursAutomatic
means the backend API will be executed on Page Load whenever there is a visible frontend component that references the response of the API. If this is not the case, the API will not be executed on Page Load.
Example
In the example below Run on page load is set to Automatic
and Superblocks shows that the API API1
is executed Automatic (Currently will do) when a page load event occurs.
The reason for this is that there is a table Table1
in the frontend which references the APIs response with {{API1.response}}
. If the API would not be executed then the table would remain empty when the page is loaded.
If no frontend component would reference the APIs response, Superblock would display Automatic (Currently Won't Run) instead.
Inputs and Permissions
The Inputs section lists all frontend components that provide input values to the API. These are snapshotted at API execution time and passed to the API.
Under Permissions you can define who is authorized to execute the backend API. This can either be everyone who has access to the application or only certain users and groups.
API response block
info
Both event handlers can also be set in the properties panel of a frontend component.
The API response block can be used to specify what happens when a backend API either executes successfully or an error occurs during execution.
Events
In the response of an API allow you to define Frontend Event Handlers that are called when a backend API returns either an onSuccess
or an onError
event to the frontend.
Scope
onSuccess
and onError
are event handlers that are run on the frontend once the backend finishes executing the API. Therefore the event handlers only have access to the frontend scope of your Superblocks Applications and to the data returned by the API via API1.repsonse
or API1.error
(assuming your backend API is called API1
). Furthermore, the frontend event handlers have no access to the output of intermediate steps such as Step1.output
, as those outputs live in the backend scope.
onSuccess
When a backend API runs through successfully without throwing any errors, a success event is returned to the frontend, and the onSuccess
event handler is called. The event handler can trigger any number of available action types. The onSuccess
event handler is not set by default.
onError
When an API step encounters an error during execution in a Superblocks Application, that API step will fail. The remaining steps will not run and the output of any failed step will be an empty object.
When a backend API fails, an error event is returned to the frontend, and the onError
event handler is called. The event handler can trigger any number of available action types. By default, the onError
event handler will trigger the showAlert()
action type that displays the error message in the UI.
Additionally, all API step errors will be available to view in the Audit Logs.
Referenced In
The Referenced In section lists all frontend components that reference a backend API to use its return values. In the following example backend API AP1
is referenced by a Table component Table1
in the frontend:
Custom response notification example
In this example, we will set up an API to provide custom messages to the end user when the API runs successfully or runs into an error.
On successful execution of the API, the end user will see a message confirming the data was fetched as expected.
When the API encounters an error, the end user will see the error message along with a custom error message indicting next steps on how to resolve the issue.