Web API plugin

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

This article covers:

How to add a data source using the Web API plugin

How to add a data source using the Web API On-Premise plugin

Web API plugin

Writing a custom data stream (advanced users)

How to add a data source using the Web API plugin

Configure the data source in SquaredUp.

If you're not using a cloud-based API and instead are accessing an API on your internal network, you should use the on-premises Web API plugin, see How to add a data source using the Web API On-Premise plugin.

  1. To add a data source 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 Configure data source page.

  2. Display Name:

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

  1. Base URL:

    Enter the base URL of the API to be used for requests, for example https://www.googleapis.com/

  2. Query arguments:

    Add any parameters that should be added to the Base URL.

  3. Authentication:

    • None: No authentication required.

    • Basic: You must enter a Username and Password.

    • 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.

  4. Headers can be added if required.

    No header information needed for the Star Wars API.

  5. 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.

  6. Test endpoint:

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

  7. Optionally, select whether you would like to restrict access to this data source instance. By default, restricted access is set to off.

  8. Click Add.

    You can also add a data source from Settings > Data Sources > Add data source, but sample dashboards are not added when using this method.

How to add a data source using the Web API On-Premise plugin

The Web API on-premise plugin allows you to add a data source that connects to an API on your internal network.

Note: This data source is an on-premises data source.

Configure and deploy an agent

If you have already created an agent in SquaredUp that you can use for this data source, you can skip this step and choose the agent group you want to use while adding the data source.

Add a Web API On-Premise data source in SquaredUp

Configure the data source in SquaredUp:

  1. To add a data source 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 Configure data source page.

  2. Display Name:

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

    You may find it useful to put the API URL in the display name. For example Star Wars https://swapi.dev/api

  3. Agent Group:

    Select the Agent Group that contains the agent(s) you want to use.

  1. Base URL:

    Enter the base URL of the API to be used for requests, for example https://www.googleapis.com/

  2. Query arguments:

    Add any parameters that should be added to the Base URL.

  3. Authentication:

    • None: No authentication required.

    • Basic: You must enter a Username and Password.

    • 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.

  4. Headers can be added if required.

    No header information needed for the Star Wars API.

  5. 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.

  6. Test endpoint:

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

  7. Optionally, select whether you would like to restrict access to this data source instance. By default, restricted access is set to off.

  8. Click Add.

    You can also add a data source from Settings > Data Sources > Add data source, but sample dashboards are not added when using this method.

 

Using the Web API data streams

How to create a data stream for a data source:

HTTP Request

The Web API plugin adds one configurable data stream (HTTP Request) which allows you to create a global data stream to query data from any HTTP API that returns JSON.

The steps for creating the data stream are very similar to those for the Run test endpoint test (when adding a Web API data source), with a couple of additional fields:

  1. Add a new data tile and scope to an instance of a Web API data source. For example Star Wars https://swapi.dev/api created earlier.

  2. Choose the + <Web API instance name> - HTTP Request data stream.

  3. Display Name:

    Enter a name for this data stream. For example, Star Wars People

  4. The Base URL from the Web API instance is shown.

  5. Endpoint path:

    Enter an endpoint path. For example, for the Star Wars API you can type people to use the People API method.

  6. Additional headers for this request:

    Enter any additional header names and values to be used.

    None are needed for the Star Wars API.

  7. HTTP method:

    GET or POST

    For example, for Star Wars choose GET.

  8. Query arguments for GET:

    If you chose GET you can optionally add any query arguments to be used.

  9. Body for POST:

    If you chose POST you can optionally enter a JSON string representing the body of the POST request.

  10. Click Send. The Result box will show an example of the resulting payload.

  11. Path to data:

    This is where you enter the location of the results set that is returned. The Result box shows you a preview of the data returned, so you can check the location of the data returned, and use that in the Path to data.

    For example, for the Star Wars API enter results.

  12. Expand inner objects:

    Objects inside the requested data path will be used to make extra columns of data.

  13. Click Save.

Writing a custom data stream (advanced users)

You may wish to create your own custom data stream for an HTTP Request using the information below. When writing your own data stream you can choose either a global or scoped entry point. You will need to write your own custom data stream if you want a scoped data stream, because the configurable data stream HTTP Request can only create a global data stream.

  1. Go to Settings > Advanced > Data Streams.

  2. Click Add new Data Stream.

  3. Enter a display name for your Data Stream.

    Note: The display name is the name that you use to identify your Data Stream in SquaredUp. It has no technical impact and doesn't need to be referenced in the Data Stream's code.

  4. Choose the Data Source this Data Stream is for.

    After you've chosen the data source a new field Entry Point appears.

  5. Entry point and code:

    To find out which entry point to select and get code examples for the Code field, see the help below.

  6. Click Save to save your Data Stream.

Example of a scoped HTTP Request data stream

Creating a custom data stream allows you to created a scoped data stream, i.e. a data stream that makes use of objects in the scope.

Which entry point do I have to select from the dropdown?

HTTP Request (scoped)

Code example:

{
    "name": "scope example",
    "matches": "all",
    "dataSourceConfig": {
        "endpointPath": "post",
        "httpMethod": "post",
        "idSeparator": "], [",
        "headers": [
            {
            "key": "header1",
            "value": "header1Val"
            },
            {
            "key": "sourceIds",
            "value": "[{{sourceIds}}]"
            }
        ],
        "expandInnerObjects": true
    },
    "rowPath": []
}

You should set the matches statement so that your custom data stream appears when you select the appropriate object types in the tile editor. You can use additional mustache constructs when using the scoped entry point: targetNodes, sourceId, sourceIds in selected dataSourceConfig parameters as shown below. The separator inserted between sourceId values in the sourceIds replacement string can be changed by setting idSeparator in dataSourceConfig.

Parameters