Skip to main content

How to use the Web API tile

Catherine
  • Updated

The Web API tile allows you to pull data from external web sources and display this data using a variety of visualisations. For example, retrieving a list of events from Splunk, or displaying figures from a CRM database.

This articles outlines how the Web API tile works, but you'll need information specific to the API you wish to integrate.

The Web API tile can utilise any API which returns JSON. In particular, REST (Representational State Transfer) APIs, which are a type of stateless web API, are ideal. The tile can connect to services using various authorization methods (more details below).

Your first port of call is the API documentation on the providers website for the service you wish to integrate with. Firstly, you should search for information about the API you want to use (for example, Google rest api docs or oauth2), and then read the API provider's documentation looking for the information you need to use in SquaredUp. Queries are written using the syntax of the remote system you're connecting to, so these will vary between vendors.

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

Along with this general article, we've also written specific articles about how to integrate with some popular APIs using the Web API tile:

Or jump into our webinar for demos integrating these applications:

For other APIs, take a look at our Community Answers site, where there's a wealth of knowledge about APIs:

Community Answers

Prerequisites

A Connect edition licence (or above) is required for this feature.

To upgrade please contact sales@squaredup.com.

To check the licence edition you are using see How to check which licence key is being used. To see what is included in different product edition licences see the Licensing Overview.

1. Adding a provider

Before you use the Web API tile you may need to add a provider. Adding an API provider is a one-time configuration task. Once a provider has been configured for a particular API provider, for example Pingdom, it can be used in multiple tiles.

A new provider can be added from system > Web API > add new provider.

Provider Type

The provider type controls how the tile authenticates with the external API:

  • Simple: No authentication, basic authentication (username and password in a header) or Windows authentication (configured automatically to use the application pool identity account).
  • Basic auth: Basic authentication. Your specified username and password will be Base64 encoded automatically.
  • OAuth: Token-based authentication according to the OAuth 2.0 standard. Many APIs use OAuth 2.0 for authorisation, and will require an OAuth provider to include the additional information about how to authorise against the service. When adding an OAuth provider you may get an message that the provider is not authorized if some of the provider configuration is incorrect (for example the username, password, secret etc), or if you use a proxy it could be that the proxy is not configured. See How to configure SquaredUp to use a proxy.
  • Azure Active Directory: When using Azure Active Directory authentication with an app or service.
  • Azure App Insights: See How to use the Azure App Insights tile
  • Azure Log Analytics: See How to configure an Azure Log Analytics provider
  • ServiceNow: See How to use the ServiceNow tile

2. Configuring the Web API tile

The Web API tile button indicates that there are more tiles available from this one button:

SNAG-0026.png

After selecting the Web API tile you will get the choice of visualisations.

Bargraph

SNAG-0027.png

SNAGIT.png

The Data Mapping section described below allows you to configure how the data is shown in visualisations.

Donut

mceclip1.png

Snag_8a965cf.png

The Data Mapping section described below allows you to configure how the data is shown in visualisations.

Line Graph

mceclip2.png

SNAGIT.png

The Data Mapping section described below allows you to configure how the data is shown in visualisations.

Scalar

A single value such as a number of customers or incidents.

mceclip3.png

mceclip0.png

Sparklines

mceclip4.png

mceclip1.png

The Data Mapping section described below allows you to configure how the data is shown in visualisations.

Grid

A table of data, e.g. incidents.

mceclip5.png

mceclip2.png

Who can create and edit Web API queries?

By default only SquaredUp administrators can create and edit Web API queries in SquaredUp. To delegate permissions to other users see Signing and Security.

Scope

The scope section (SquaredUp v4.2 and above) allows you to specify SCOM objects which can be used to insert an array of SCOM object properties into the search query.

The Web API tile scope can be particularly useful on perspectives. For example, you might like to show Splunk events for a dynamic list of servers found as children of an Enterprise Application (EA) object.

See How to scope tiles on dashboards and How to scope tiles on perspectives

Provider

The provider dropdown list allows you to select any API provider you have created in system > Web API.

HTTP mode or method

Both GET and POST requests are available through the Web API tile. The documentation for your web service will indicate which is needed, although typically this will be a GET request.

The URL is that of the external web service and can contain query parameters, e.g. https://myservice/?filter=customers

Headers & Data

The Web API tile allows you to send additional data to the web service along with your request in the form of headers & data. Headers are HTTP headers and in the context of this tile, are typically used for authentication or specifying content types such as JSON.

You are also able to add additional data fields which are sent with the request. For a GET request these are sent as query string parameters, whereas for a POST request, they are sent in the request body.

Using Variables

A single variable can be added to the search query in order to inject a SCOM property that will make the query results relevant to the object being shown by the perspective. This is ideal when browsing to a server and injecting that server name into the query.

For example, the variable {{displayName}} might be used so that the query is specific to the object that the perspective is showing.

For more information see Adding a Splunk query to a perspective using a single variable.

An array of variables can also be sent in the search query using multi-object query building via mustache style code snippets (SquaredUp v4.2 and above). It is particularly useful to be able to use an array of variables when creating perspectives for Enterprise Application (EA), where you may wish to inject the names of all the servers appearing in the EA map to return API data specific to those servers. The scope section is used to define the array, which is then referenced in the search query see How to scope tiles on dashboards.

In SquaredUp v4.2 and above mustaches in the query can include JavaScript to manipulate the SCOM property values being inserted. For example, simple JavaScript string manipulation functions such as split() and substring() can be used.

mceclip8.png

When you click the mustache editor button {{}} you will see a list of example scope code snippets, along with the snippet result based on the selected scope context for the tile.

In the query field select the relevant snippet for your API query and it will be inserted into the query field where you can edit it as required.

In SquaredUp v5 and above the mustache button has been added to the data section even when you're not on a perspective, so you can use JavaScript to manipulate the values, or use one of the supplied date snippets:

SNAG-0028.png

For example, see Adding a Splunk query to a perspective using an array of variables

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.

SNAG-0029.png

Grid Columns

Clicking edit next to columns shown in the Grid Columns section allows you to edit the format of the data displayed. For example, you can use mustache syntax with timeago to convert Unix timestamps to show a readable date and time:
mceclip1.png

You may also like to add further columns to show additional data, for example when using the PagerDuty API.

Click Add, give the column a name, such as Service, and in the custom template box click the mustache helper button mceclip2.png and select the value you require, for example {{value.service.summary}} then click done.

mceclip6.png

For help customizing the columns of data see How to use the Grid designer when configuring tiles.

Data Mapping

For Web API data visualisations, such as line graphs, sparklines, donuts, and bar charts, the data mapping section allows you to control how the data is shown.

Data aggregation

This is used for donuts and bar charts.

When the data provided by the API has already been aggregated in some way use the setting none.

When the API itself doesn't give you any summary information you can count or sum values across the results and display them in a donut.

For example, for Azure DevOps you might like to count {{result}} or {{state}} values.

For Pingdom 'checks' you can create a donut counting the number of instances of the status 'up' and the number of instances of 'down':
mceclip1.png

Grouping

This is where you can specify which field you want to graph. Select the field from the drop down list that you want to chart.

For example, for Zendesk you might want the grouping to be the status field, using the count aggregation method, to show the count of tickets of each status:

mceclip0.png

 

You can also calculate the value, perhaps from two properties, or convert from a string to an integer, or combine several values.

For example, this image shows an if calculation for a SolarWinds donut:

mceclip2.png

Timestamp

Line graphs and sparklines also include a timestamp field, as the time series is used for the x-axis of the graph. Timestamps that are supported are Unix timestamp in milliseconds or ISO 8601 date format. Some APIs, such as Pingdom, give the timestamp in seconds rather than milliseconds, so in the Data Mapping timestamp mustache you'll need to use {{starttime*1000}} to convert into milliseconds).
mceclip4.png

Metrics

When the data aggregation is not set to count, you can specify what value you want to use as the metric value (y-axis) from the drop down list. Often this will be as simple as {{count}}. You can also calculate the value, perhaps by subtracting two values, or converting from a string to an integer, or combining several values.

Some APIs return multiple metrics from a single request, such as New Relic, and as shown here for PagerDuty. If configured, this will display each metric configured on the same visualisation (such as multiple lines on a line graph):

mceclip0.png

Grid Options - Row link

Configuring the row link property will automatically link each row to a parameterised hyperlink. Depending on the API you are using it may be possible to use a parameter to link each line of your results to a page specific to that result. Sometimes this is achieved by by adding an ID field to the end of an appropriate URL.

Here are some examples from API's we've used:

For ServiceNow incidents https://<your-instance>.service-now.com/nav_to.do?uri=%2Fincident.do%3Fsys_id%3D{{sys_id}}

For PagerDuty incidents {{incident.html_url}}

For Azure DevOps projects https://dev.azure.com/<your-instance>/{{name}}

For Azure DevOps builds https://dev.azure.com/<your-instance>/_build/results?buildId={{id}}

For Zendesk tickets https://<your-instance>.zendesk.com/agent/tickets/{{id}}

mceclip7.png

You can use the mustache helper button to browse through the drop down list of data available to see if there is something appropriate for your API. For help customizing the columns of data see How to use the Grid designer when configuring tiles.

Paging and limiting the results size

One thing to keep in mind when making queries is that the WebAPI 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 at this time.

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! 

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.

  1. Browse to http://jsonplaceholder.typicode.com/posts The data shown is a list of posts which we can show in SquaredUp 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 when configuring tiles.

  7. Click done.

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

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.

Related articles