Skip to main content

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.

Query different databases and APIS before merging the data with Python or Javascript

Working with Superblocks APIs​

Referencing Component Data​

You can use {{}} in SQL / REST / GraphQL steps to reference components in the Canvas.

Reference components in the canvas with curley braces

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.

Reference a previous API step using the step name and accessing the output attribute

{{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:

Reference output of another API within an API step using API1.response

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:

Fill the Table data with the response of the GetOrders API

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:

Run API1 every time a row in the table is selected

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 event
  • Never means the API will never be executed when a Page Load event occurs
  • Automatic 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.

The list of API triggers and the Page Load settings of a backend API

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.

See a list of Inputs to a backend api and set permission for it

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.

A backend API response block with the default settings

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:

The **Referenced In** section lists all frontend components that reference a backend API

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.

Define custom error notifications for APIs within the API builder

On successful execution of the API, the end user will see a message confirming the data was fetched as expected.

Define custom success notifications for APIs within the API builder

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.

Notifications are shown to the user to help confirm actions or to troubleshoot