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).
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.
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 (Squared Up v3.4 onwards).
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 Squared Up 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
2. Configuring the Web API tile
The Web API tile button displays a little plus up the top right. This indicates that there are more tiles available from this one button.
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.
Grid: a table of data, e.g. incidents.
The provider dropdown list allows you to select any provider you have created in system > Web API > add new provider, along with 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.
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.
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 Squared Up.
http://jsonplaceholder.typicode.com/postsThe data shown is a list of posts which we can show in Squared Up as a table.
Create a new dashboard and click on the Web API tile.
Select Web API (Grid) and click next.
Select generic from the drop down list for the provider, and click next.
Paste the web address from step 1 into the URL box, and click next.
For help customizing the columns of data see How to use the Grid designer when configuring tiles.
The data from the external API is now shown in Squared Up.
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.
For guidelines and a walkthrough of how to integrate ServiceNow with Squared Up see How to use the Web API tile with ServiceNow.
For advice and walkthroughs of integrating Splunk see How to use the Web API tile with Splunk.
How to configure Squared Up to use a proxy