Web API plugin

The Web API plugin allows you to query data from any HTTP API that returns JSON, and then visualize that data. This is particularly useful if there isn't a SquaredUp plugin available for your data source.

Click the following link for additional content such as blogs, videos, use cases, and more:

Web API

For detailed instructions on creating Web API tiles, see How to configure a Web API tile.

For detailed definitions of data stream parameters, see Web API data stream parameters.

Adding a data source

To add a data source, open the relevant workspace and then click on the + next to Data Sources on the left-hand menu in SquaredUp. Search for the data source and click on it to open the Add data source page. Adding from the data sources page

Before you start

1. Will SquaredUp need to connect to this data source via a relay agent?
2. Configure the data source in SquaredUp

Will SquaredUp need to connect to this data source via a relay agent?

This plugin is a hybrid plugin, meaning it can connect to either a cloud or an on-prem data source.

• If your data source is available on the internet, then you do not need to connect via a relay agent.
• If your data source is on a private network and is not publicly accessible, then you will need to configure a relay agent before you configure the plugin. See Deploying a relay agent.

If you have already created a relay agent in SquaredUp that can access this data source, then you can skip this step and choose Connect via relay agent when Configuring the data source.

Configuring the data source

For testing you could use the JSON Placeholder API. This is a JSON REST API that will show you some sample data: http://jsonplaceholder.typicode.com

1. Display name:
   Enter a name for your data source. This helps you to identify this data source in the list of your data sources.

   
   For example: JSON Placeholder

2. Connect via relay agent:
   If you are connecting to an on-prem data source, select this toggle so you can use a relay agent to connect securely.

   Then, select the Agent Group that contains the agent(s) you want to use. Agent groups are managed from Settings > Relay Agents.

3. Base URL:
   Enter the base URL of the API to be used for requests.
   For example you could use http://jsonplaceholder.typicode.com For this sample API the provider needs no further configuration so just click Add and then go to Configuring a Web API tile.
4. Query parameters:
   Optionally, add any parameters that should be added to the Base URL. You may prefer to add these in the tile configuration so you can use different queries on different tiles.
5. Headers:
   Optionally, click to configure headers for the request. Enter key:value pairs for each of the headers you add.
6. Authentication:
   Choose how to authenticate the connection. Choose from:
   • None: No authentication required.
   • Basic: You must enter a Username and Password.
   • Digest: Enter a Username and Password to use with Digest authentication, which ensures that passwords are hashed and mitigates replay attacks.
   • OAuth 2: Token-based authentication according to the OAuth 2.0 standard. Many APIs use OAuth 2.0 for authorization, and will require an OAuth provider to include the additional information about how to authorize against the service. If this option is selected, follow the steps in Configure OAuth 2.0 below.
     
     Configure OAuth 2.0

     Specify the details for your required OAuth 2.0 flow. For more detailed information see OAuth 2.0 Configuration.

     1. Client ID:
        Enter the ID provided by your client application.
     2. Client Secret:
        Enter the secret provided by your client application.
     3. Authorization Scope:
        Enter your required access scopes for the third-party application server you are using. For example, if you are using the Web API plugin to access the https://www.googleapis.com/ API and you wish to use the drive/v3/files endpoint, you can use the authorization scope https://www.googleapis.com/auth/drive.readonly.
        If you require more than one scope, you add them all here separated by spaces.
        Offline access

        The Web API plugin requires offline access to be requested, which requires the correct scope to be entered, dependent on the authentication server being used:

        • Atlassian: Request the offline_access scope.
        • Google APIs: Offline access isn't requested via a scope at all. Instead, you must add the access_type = offline and include_granted_scopes = true query arguments to the Authorization URL.

     4. Configure the Token section as follows. These fields define how your application requests an access token from the authorization server:
        1. Token URL:
           Enter the URL of the third-party authentication server you are using. For example, https://oauth2.googleapis.com/token.
        2. How to send credentials to the Token URL:
           Select where you want the client credentials you entered above to be included in the OAuth 2.0 request.
        3. Query parameters:
           Specify any additional parameters that must be appended to the token request URL as key:value pairs.
        4. Headers:
           Define any HTTP headers that must be included in the token request as key:value pairs.
        5. Send access token in query parameters:
           Enable this for services that require the access token as a query parameter. When disabled, access token is supplied as an Authorization Bearer header.
     5. Configure the Authorization section as follows. These fields define how your application obtains authorization tor resources using OAuth 2.0:
        1. Grant Type:
           Select the OAuth 2.0 flow you need to use. Choose from:
           • Authorization Code: Enter the Authorization URL of the authorization server you are using (for example, https://www.googleapis.com/) and then click the Sign In button below. You are redirected to the authorization sign in page.
             Upon returning to SquaredUp , if the request was successful, the Sign In button shows you as logged in.
           • Client Credentials: No additional details are required.
           • Password: You must enter a Username and Password.
   • JWT Bearer: Uses a signed JSON Web Token (JWT) to obtain or present bearer credentials for authentication. Commonly used for service accounts and server-to-server API integrations.
     
     Configure JWT

     Specify the details for your required JWT Bearer flow.

     1. Add token to:
        Select where the generated JWT should be included in API requests. Choose from:
        • Request Header: Adds the JWT to the Authorization header.
        • Query Param: Adds the JWT as a query string parameter in the request URL. When selected, the Query parameter name field displays. Use this to specify the name of the query parameter to attach to.
     2. Algorithm:
        Select the signing algorithm used to generate the JWT signature. This must match the algorithm expected by the target API.
     3. Secret:
        Enter the secret, private key, or signing key used to generate the JWT signature. The required format depends on the selected algorithm.
     4. Secret is base64 encoded:
        Enable this option if the configured secret is Base64-encoded. The secret will be decoded before being used to sign the JWT.
     5. Payload:
        Enter the JWT payload (claims) as a JSON object. The payload is included in the JWT body before it is signed.
     6. Show advanced JWT settings:
        Select to display the following additional JWT configuration options:
        1. Request header prefix:
           The prefix applied when adding the JWT to a request header. For example, Bearer produces Authorization: Bearer <token>. Leave blank to send only the token value.
        2. JWT headers:
           Optional JSON object containing additional JWT header values, such as kid, typ, or other API-specific header claims.
7. Scripting:
   Enable this option if you need to run a JavaScript pre-request script before each data stream request. This allows you to perform custom authentication flows, generate request signatures, or modify request headers before the request is made:
   1. Secrets:
      Define values that your script can access, such as API keys, tokens, or signing secrets. Click Add variable to create a new secret key-value pair.
      
      Click the padlock
      next to a value to encrypt it when stored. This is recommended for sensitive information such as API keys, client secrets, and authentication tokens.
      
      These are accessed in your script via the secrets object. For example:
      
      Copy

      const token = secrets.apiToken;
      const keyId = secrets.keyId;

   2. Pre-request script:
      Enter the JavaScript to run immediately before each HTTP request is sent by the data source. For example, to add an authorization header using a stored secret:
      
      Copy

      headers["Authorization"] = `Bearer ${secrets.apiToken}`;

      Script variables

      The following variables are available to pre-request and post-request scripts. Some variables are writable and can be modified by the script, while others are read-only.

      Variable	Writable?	Description
      url	Yes	The full request URL. Modify to change the endpoint or query parameters before the request is sent.
      method	No	The HTTP method used for the request (GET or POST).
      headers	Yes	The HTTP request headers. Add, remove, or update headers before the request is sent.
      body	Yes	The request body for POST requests. Modify to change the data sent to the API.
      state	Yes	Persistent state shared between script executions. Store values such as access tokens or expiry times for reuse in future requests.
      secrets	No	The secrets configured in the data source. Use these to securely access API keys, tokens, passwords, and other sensitive values.
      response	No	The raw HTTP response returned by the API. Available only in post-request scripts.
      data	No	The parsed response body. Available only in post-request scripts.
      result	Yes	The data returned to the tile. Set this in a post-request script to shape the final output.
      metadata	Yes	Column metadata returned with the result. Modify to override metadata defined by the plugin.
      pagingContext	Yes	Paging state passed to the next request during pagination. Set this in a post-request script to continue retrieving paged results.
      api	No	Provides helper functions for reporting warnings and errors during script execution.
      context	No	Information about the current request, including the data source configuration and execution context. Contains the following (immutable) properties: dataSources: A single-element array containing the configuration of the Web API data source instance (pluginConfig). dataSourcesByName: A plain JavaScript object (POJO) containing the data source configuration, keyed by the data source display name. objects: The collection of objects supplied to the current data stream request. timeframe: The timeframe selected for the current data stream request. pagingContext: The paging context returned by the previous request during pagination. config: The configuration for the current data stream (dataSourceConfig).

8. Ignore certificate errors:
   If you activate this checkbox the data source will ignore certificate errors when accessing the server. This is useful if you have self-signed certificates.

9. Test endpoint:
   Optionally, you can select Test endpoint to run a test request and see an example payload.
   
   Test endpoint

   Enter the details of an endpoint you'd like to run a test against to see what is returned. The information entered here is only used for the test.

   1. Endpoint path to test:
      Enter an endpoint path.
   2. Additional headers for the test:
      Enter any additional header names and values to be used for the test.
   3. HTTP method for the test:
      GET or POST
   4. Query arguments for the test GET:
      If you chose GET you can optionally add any query arguments to be used for the test.
      For example, for the JSON placeholder API you would use GET and /posts or /users or /albums
   5. Body for test POST:
      If you chose POST you can optionally enter a JSON string representing the body of the POST request.
   6. Click Send.
   7. The Result box will show the resulting payload.

10. Restrict access to this data source:
    Optionally, enable this toggle if you only want certain users/groups to have access to the data source, or those with the permission to link it to new workspaces. See data source access control for more information.

11. Click Add.

Testing and troubleshooting

You can use the Test endpoint section of the plugin configuration (see above) to check the available endpoints and view the resulting data.

When configuring the tile it's really helpful to open the Troubleshooting panel by clicking Open troubleshooting

If you encounter an error refer to the guidance or contact our support team in-app or via SquaredUp Support

For errors on dashboard tiles see Troubleshooting tiles.

Next steps

Data streams

You can use these data streams to create new tiles to show data, or if there are preconfigured dashboards installed you can copy or edit those.

The following data streams are installed with this plugin.

Configuring a Web API tile

Web API tiles are configured via the tile editor the same as every other data source, however the complexity of the configuration itself can vary significantly depending on the API you are accessing.

In some circumstances, the information you provided when configuring the data source may well suffice to return the data you need. In others, you may be required to include an endpoint, payload, query parameters, headers or paging details.

Each of these are configured on the corresponding sub-tab via the Parameters tab of the tile editor.

For full detailed instructions on building out your Web API tile's HTTP requests, see How to configure a Web API tile.

For detailed information on each configuration setting, see Web API data stream parameters.

Was this article helpful?