Skip to main content

Building REST requests

The REST request interface in Superblocks makes it easy to send HTTP requests to any API. Whether you're using an internal API, or integrating with a third-party's API, send any request you want to fetch, add, delete, or update data using REST.

Annotated REST interface

The REST request interface will appear when you add any of the following types of steps to your APIs:

Actions​

Superblocks' REST requests support a range of Actions that you can select from to configure what operation your API step will perform.

For REST based integrations, the default action is often set to Generic HTTP request, which you can use to fully customize the request being made.

For a faster development experience, select one of the pre-configured Action endpoints. When you select an endpoint, the Method and URL will be automatically set, along with any required Query parameters and Headers needed for the request.

Integration Actions menu showing Action endpoints for a REST API

tip

Want to customize the Actions for your REST integration? Add an API Specification to your integration. This not only adds Action endpoints but also lets you easily explore your API docs as you build with Doc Explorer.

Request form basics​

The REST request form include all the configurations needed to connect to a webserver and execute your request. Every request needs a URL and method. Specify additional details based on the requirements of the endpoint you're calling.

Annotated REST request interface

Method​

Select the method for the request from the dropdown. If you selected an action from the actions this will be selected for you, otherwise the GET method is selected by default. You can use a variety of methods, including

  • GET - retrieve data
  • POST - add new data
  • PUT - replace existing data
  • PATCH - update some existing data fields
  • DELETE - delete existing data

URL​

Each request requires a URL representing the endpoint you want to call. Add the endpoint manually, or have it pre-filled by selecting an API endpoint in the actions. When using an integration, the Base URL will be set for you based on the integration configuration.

Update the URL with required path parameters by providing a value or add a binding to reference user input, frontend variables, or workflow parameters.

REST request url with binding to a dropdown's selected item

Query parameters​

Send query parameters with your request by adding them directly to the URL or as key-value pairs in the Query parameters section. When using an API endpoint from the list of pre-configured actions, any required query parameters will be automatically added to the request form for you.

Required query parameters are automatically added to the REST form

Body data​

Use the Body section to specify the data you want to send with your request. You can send different types of body data to suite your API. Choose the data type you need based on the expected request body for the API endpoint.

JSON​

Use the JSON body type to send JSON data to your API. The JSON body data field supports syntax-highlighting, as well as commenting by using the // for single-line deliminted comments, or /* */ for multi-line.

An example request body that matches the API's required schema will be automatically added for you when using pre-configured actions.

Raw​

Use the Raw body type to send anything you can enter as text.

info

Be sure to add the appropriate Content-Type header to the Headers section based on the type of content you're sending in your request.

Form​

Website forms often send data to APIs as multipart/form-data. Replicate this using the REST request Form body type. Form data lets you send key-value pairs and specify the content-type of each item.

Attach files to form data by setting the item's content-type to File, then provide a filename and file content. Content can either by manually created, or read the content of the FilePicker component.

REST request Form body that uses FilePicker contents as input

Headers​

Some APIs require you send particular headers along with the request. You can set these in the Headers section. Enter a key-value pair of the headers up send with your requeset.

REST request headers, including automatically added headers

info

Superblocks automatically adds certain headers for you based on your selects and how you've configured your integration. Select hidden next to the Headers label to view the generated headers.

Response type​

Use the Response type to tell Superblocks what media type to use for the data returned. Superblocks will attempt to detect the media type for you based on the Content-Type response header sent by the API. Alternatively you can set a response type if the response header is not implemented or is a data type not supported by Superblocks.

Exploring docs​

The doc explorer located to the right of the request form makes it easy to build your request at lighting speed. From here you can:

  • Explore available endpoints - Search list of all of the available endpoints to choose from in the Actions menu
  • View documentation - When you select an endpoint Action, the Doc Explorer snaps to that endpoint's documentation. Docs provide valuable information like the required headers and query parameters, the request schema and examples, responses schemas and codes the endpoint uses, and sometimes even scopes needed to access the endpoint.

API Documentation Explorer

Standard HTTP requests​

Superblocks' REST APIs can be used to make both standard HTTP requests and stream data from APIs that implement server-sent events. Follow the instructions in this section to make a standard HTTP request.

Configure request​

To configure a REST API to make a standard HTTP request:

  1. Add your REST API to your API
  2. Configure your HTTP request using the REST request form
  3. Click Run API to execute your API with your HTTP request

Response data​

Once your API has run, you can view the response from you API under Response. The response section includes:

  • Result - Shows the payload returned by the API along with the request status and timing
  • Request - The full request executed by the backend shown as a CURL request.

REST request form showing a JSON response payload

Use the response from your REST API in subsequent steps using <STEP_NAME>.output.

Streaming requests​

Server-sent events is a standard for real-time communication between the client and server over HTTP/S. With Superblocks' REST APIs, you can consume server-sent events to create real-time applications like chatbots, live event feeds, and more.

Configure request​

To configure a REST API to consume server-sent events:

  1. Add a Stream block
  2. Add your REST API to the Trigger section of the Stream block
  3. Configure your HTTP request using the REST request form
  4. Set the Response type to Raw

REST API in Stream Trigger

Process response​

Sever-sent events are text data which is encoded using UTF-8. Messages have some combination of fields or text designating the client connection has been closed.

To receive, parse, and access event message fields, parse the event using Process message.

  1. In the Stream block, enable Process message
  2. Add a Python or Javascript block to parse the message

Parse event data with Stream Process block

Response data​

Unlike standard HTTP requests, you won't be able to access streaming reqest output in the block's Results tab. Instead, access response data by adding Process steps to your API.

To use the output of your streaming requests in an Application, configure an onMessage event handler to use your messages to update your App's UI. Learn more about the streaming data to the client.

Troubleshooting​

After running your API, you'll see any errors returned by your request in the response section of the request form.

If your REST request isn't behaving as expected, there can be many possible reasons. This guide discusses how to troubleshoot and provides common issues and their causes.

info

This guide specifically discusses troubleshooting REST requests. To troubleshoot issues with the Superblocks platform, see our general Troubleshooting guide.

Debugging your requests​

Since APIs in Superblocks run on a backend web server, you won't be able to see your REST requests in your browser's console. To debug REST requests issued in the backend, Superblocks provides you the full request as a CURL command in the Request tab of the response section. Use this command to debug issues with your request by copy/pasting it to your terminal or a REST client like Postman.

Executed requests section of the API response