Web API tile

About Web API tiles

The Web API tile allows you to pull data from external APIs and display this data using a variety of visualizations.

What kinds of APIs are supported?

The Web API tile works with any REST API that returns JSON.

How do I connect to the API I want to use?

The connection details are not stored in the tile, but in the provider. You need to create a provider before you can use the Web API tile. Adding an API provider is a one-time configuration task to be carried out by a SquaredUp DS administrator.

See How to add a Web API provider.

How do I get data from the API into the tile?

The Web API tile supports GET and POST requests. For the format of those requests, you need to refer to the API documentation of the service you want to integrate with.

Should I use the Web API tile or one of the dedicated tiles?

For the most used APIs we now have dedicated tiles to make integration quicker and simpler:

If you want to display incidents or change requests from ServiceNow,
you can use the dedicated ServiceNow tile which is quick and easy to
set up.
For any other ServiceNow data, you need to use the Web API tile:
How to use the Web API tile with ServiceNow

If there's no dedicated tile for the API you want to use, you can always use the Web API tile. Here are articles with examples about how to integrate with some popular APIs using the Web API tile:

Further help for integrating with APIs:

If you're looking for some real-life examples of dashboards, check out the Dashboard Gallery. You'll find dashboards that users from SquaredUp and the Community have created to help you get the most out of SquaredUp DS:

Dashboard Gallery

How to configure a Web API tile

If you don't already have a provider for Web API tiles, you need to create one before you can configure your Web API tile (How to add a Web API provider).

  1. Add a new tile to a dashboard and choose Integrations > Web API.
  2. Choose the visualization for your Web API tile:

  3. Provider:
    Choose the provider you want to use for this tile.

    You can use generic and dedicated integrations to create your own providers. Of course, a dedicated provider like ServiceNow will only work with the ServiceNow API.

  4. HTTP mode:
    Choose if you want to use a GET or POST request.
    URL:
    This is the query URL. The query URL gets added to the URL you defined in the provider you are using for this tile.
    Example:
    You want to query https://myservice/customers/tickets.
    Your provider URL is https://myservice/
    Your query URL needs to be customers/tickets
    Note:

    By default, only SquaredUp DS administrators can create and edit Web API queries in the Web API tile.

  5. Headers & Data:
    Headers:
    The HTTP header. Here you can enter properties for authentication or specify that the content type of the return data needs to be JSON. Please refer to the API documentation of the API you are using to see what properties are supported.
    Data:
    If you are using a GETrequest:
    Here you can add query string parameters to your query string.
    If you are using a POSTrequest:
    Here you can add additional data to the request body of your query. You can send query string parameters as a form, and other data in the content type json, xml, or text.
    Please refer to the API documentation of the API you are using to see what parameters and content types are supported.
    Note:

    By default, only SquaredUp DS administrators can create and edit Web API queries in the Web API tile.

  6. Response Data:
    This is where you enter the location of the results set that is returned. The response data box shows you a preview of the data returned, so you can check the location of the data returned, and use that in the key path.
  7. Configure the settings for your visualization:
  8. Click done to save the tile.

    The tile now shows data according to your settings.

Paging and limiting the results size

One thing to keep in mind when making queries is that the Web API tile does not support request paging. Some APIs will not return all the query results in a single request (say limiting each request to only 100 items), and require the user to make multiple subsequent requests to get the entire results set. Since there is no standard way of doing this, we are currently unable to support it.

This may mean your tile is only able to display the most recent results, and may be an issue if you are say trying to query for every incident in the system and display a donut showing the counts of incidents in each status. To avoid this, if you need to display summaries either query API endpoints that provide summarised information for you, or make sure you indicate in the tile name/description that this may be only recent results.

If your API does not page requests and instead can return large datasets in a single request, consider adding limits to your query if the API supports it. If your query returns 10,000 results, you may experience a tile that takes a long time to load and display data. Don't show data for all time when the last 30 days will do!

Custom code tips and examples for the Web API tile

Walkthrough: Configuring the Web API tile to show a JSON placeholder example

http://jsonplaceholder.typicode.com/ is a JSON REST API used for testing services and this example demonstrates how you would retrieve data from this API and show it using SquaredUp DS.

  1. Browse to http://jsonplaceholder.typicode.com/posts The data shown is a list of posts which we can show in SquaredUp DS as a table.
  2. Create a new dashboard and click on the Web API tile.
  3. Select Web API (Grid) and click next.
  4. Leave the scope as it is and click next.
  5. Select generic from the drop down list for the provider, and click next.
  6. Paste the web address from step 1 into the URL box.
    For help customizing the columns of data see How to use the Grid Designer
  7. Click done.

The data from the external API is now shown in SquaredUp DS.

It is important to note that this data will refresh along with the rest of your dashboard and is great for showing tabular data such as a list of open support tickets or configuration changes.

Was this article helpful?


Have more questions or facing an issue?