8 minute readApplies to: v4

How to use the Web API tile

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

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

The information below outlines how the Web API tile works, but your first port of call is the documentation for the service you wish to integrate with. Firstly, you should search for information about the API you want to use (search rest api docs or oauth2), and then read the API provider's documentation looking for the information you need to use in SquaredUp.

For the most used APIs we've now created 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:

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

Community Answers

1. Adding a provider

Before you use the Web API tile you may need to add a provider. 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 use the Azure Log Analytics tile
  • 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:

Web Api tile

After selecting the Web API tile you will get the choice of Web Api (Scalar) or Web Api (Grid).

Scalar: a single value such as a number of customers or incidents.

Web Api Scalar

Grid: a table of data, e.g. incidents.

Web Api Grid

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.

Provider

The provider dropdown list allows you to select any 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.

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.

Web API Snippets

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.

For more information see Adding a Splunk query to a perspective using an array of variables

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.

ServiceNow

For guidelines and a walkthrough of how to integrate ServiceNow with SquaredUp see How to use the ServiceNow Tile.

Splunk

For advice and walkthroughs of integrating Splunk see How to use the Web API tile with Splunk.

How to use the ServiceNow Tile

How to use the Web API tile with Splunk

How to use the Azure App Insights tile

How to use the Azure Log Analytics tile

How to use the Web API tile with Google APIs such as Google Analytics

How to use the Grid designer when configuring tiles

How to configure SquaredUp to use a proxy

Squared Up Ltd. (c) 2020Report an issue with this article