6 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 open incidents from ServiceNow, 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:

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, including ServiceNow, 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
  • Azure Log Analytics

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

Scope

The scope section allows you to specify resources which can be inserted into the search query.

For more information see How to scope tiles

Provider

The provider dropdown list allows you to select any provider you have created in system > Web API > add new provider, or generic provider.

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 resource that will make the query results relevant to that resource. This is ideal when browsing to a server and injecting that server name into the query.

For example, the variable {{Name}} might be used so that the query is specific to the resource shown.

An array of variables can also be sent in the search query using query building via mustache style code snippets. The scope section is used to define the array, which is then referenced in the search query.

Mustaches in the query can include JavaScript to manipulate the resource values being inserted. For example, simple JavaScript string manipulation functions such as split() and substring() can be used.

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.

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.

    Web Api tile

  3. Select Web API (Grid) and click next.

    Web Api Grid

  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.

How to use the ServiceNow Tile

How to configure SquaredUp to use a proxy

How to use the Grid designer when configuring tiles

How to configure SquaredUp to use a proxy

How to use the App Insights tile

How to use the Logs tile

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