Skip to main content

Create API Request

API requests allow your custom widgets to connect with external data sources and services. This guide will show you how to create and configure API requests in the Widget Builder. This tutorial is working for the API Request extra form and for the form in custom Widgets.

Creating a New API Request​

  1. In the Widget Builder interface, navigate to the "API" tab in your widget project.
  2. Click the "+ New API Request" button.
  3. Give your API request a descriptive name (e.g., "Get Twitter Feed" or "Fetch Weather Data").

Configuring the Request​

Basic Configuration​

  • URL: Enter the full endpoint URL for your API (e.g., https://api.example.com/data)
  • Method: Select the appropriate HTTP method (GET, POST, PUT, DELETE, etc.)
  • Headers: Add any required headers like Content-Type: application/json
  • Body: Add any body like json or text

Authentication​

You can use Staffbase authentication tokens in your requests by leveraging the Handlebars helpers:

// For ID token Authorization:
{{staffbaseIdToken}}
// For access token Authorization:
{{staffbaseAccessToken}}

See the Use Authentication Tokens guide for more details.

To hide the authentication data in the headers or body, you can activate the option Route through Widget Builder.

Using handlebars​

The handlebars helpers and data are activated for the fields url, headers and body. You can leverage these helpers to manipulate data, format JSON, and handle authentication tokens.

Here some examples, more information you can find on the page Handlebar Helpers

{{! Convert an object to JSON string }}
{{json settings.complexObject}}

{{! URL encode a string }}
https://api.example.com/search?q={{encode settings.searchTerm}}

{{! Decode and use JWT token data }}
{{#with (decode_jwt staffbaseIdToken)}}
  {{! Now you can access properties from the decoded token }}
  "userId": "{{sub}}", "email": "{{email}}"
{{/with}}

{{! Extract specific fields from JWT token }}
"userId": "{{extract_jwt staffbaseIdToken "sub"}}"

Example: POST Request Body with User Data

{ "user": { "id": "{{extract_jwt staffbaseIdToken "sub"}}", "name": "{{settings.userName}}",
"preferences":
{{json settings.userPreferences}}
}, "timestamp": "{{formatDate "yyyy-MM-dd"}}" }

Request Body​

For POST, PUT, and PATCH requests, you can configure the request body:

  1. Select the appropriate Content-Type (e.g., JSON, form data, raw text) in the headers.
  2. Enter the data you want to send
{
  "user": "example",
  "message": "Hello from Widget Builder"
}

Query Parameters​

For GET requests or to add URL parameters, use the query parameters section:

  • Add key-value pairs that will be appended to your URL
  • Example: adding key=value will result in ?key=value being added to your URL

Using Variables​

You can make your API requests dynamic by incorporating variables:

  • Widget settings: {{{settings.yourSetting}}}
  • Custom variables: {{{variables.yourVariable}}}
  • Handlebars helpers: {{{formatDate 'yyyy-MM-dd'}}}

Example URL with variables:

https://api.weather.com/forecast?location={{{settings.location}}}&date={{{formatDate 'yyyy-MM-dd'}}}

Testing the Request​

On every change in the form, the editor refetches the data.

  1. Click the "Load data" button to see the response from your API
  2. The response will be displayed in the "Response" panel

Using the Response Data​

After setting up your API request, you can use the response data in your widget layout:

<div class="weather-widget">
  <h2>Weather for {{data.location}}</h2>
  <div class="temperature">{{data.temperature}}°C</div>
  <div class="description">{{data.description}}</div>
</div>

The data from your API response is available under data.

Tips for API Requests​

  • Rate Limits: Be aware of API rate limits, especially for testing
  • CORS: Ensure the API allows requests from your domain (CORS enabled)