Working with REST APIS - Part 2

Welcome to Part Two of our two-part series on REST APIs. Now that you’ve learnt all about what REST APIs are and how they work, let’s have a look at how you can get the most out of your REST APIs. We will illustrate this through the example of integrating SquaredUp with the ServiceNow REST API.

If you find yourself wondering: What exactly is a REST API, and how does it work? head over to Part One of this series.

Putting it all in action – Integrating SquaredUp with the ServiceNow REST API

ServiceNow is an IT Service Management tool that helps IT departments to respond to incidents, like system outages, as well as more mundane change requests like “I need my password reset” or “The printer’s out of toner”. These incidents and change requests represent the users’ view of what’s happening to our servers and applications, whereas SquaredUp is already displaying SCOM data for these same servers and applications - the machine view if you like. The power of SquaredUp’s Web API functionality means that we can use the ServiceNow API to marry up both the users’ view and the machine view to get the best possible understanding of what’s happening to our critical systems. Let’s walk through what we need to do to make this happen in the next section.

Getting the OAuth prerequisites in place

Services that restrict access to their APIs using OAuth normally require that you configure an entry for your client application in the administration portal for the service. In the example below I have created a new OAuth Client entry in the ServiceNow administration portal. The only thing I need to do is enter a name for it and check that its scope (the data ServiceNow should allow the application access) is appropriate for my needs. Once created, the Client ID and Client Secret are available for when I configure SquaredUp to authenticate as this client application.

Now we can configure SquaredUp with the client details from ServiceNow. First, we select oauth from the provider type selections and then choose the password grant type from the grant type selections. We give the provider a name of our choice (SquaredUp Blog in this instance). At this point we need to know the base URL for the API and its token URL. The base url is simply the part of the URL that is common to all requests to this API. In my inventory management example, this would be http://api.myinventory.local/ . Every call I made to this API contained this in its URL. The token url is the URL that the client application will request an OAuth token from. Both the base URL and the token URL should be available from the public API documentation of the service you want to use.

Finally, we’re going to enter our ServiceNow username and password, together with the client id and client secret we obtained when we registered the client application in the ServiceNow portal.

Now we can click add provider. If all goes well we’ll see a green tick against the provider we just created in SquaredUp:

Just for interest’s sake, let’s have a look at what happened in the background using an HTTP capture tool. We can see that SquaredUp made an HTTP call to the Token URL we provided using the POST method. The HTTP Status that was returned was 200, so it was a success:

If we examine the HTTP Headers and Body of this call, we can see that SquaredUp submitted the Client ID, Client Secret, Username and Password in the body of the request and ServiceNow responded with, amongst other things, an Access Token and a Refresh Token.

Brilliant. It looks like we’re all set and ready to pull data out of ServiceNow. Let’s create a WebAPI tile in SquaredUp and select the SquaredUp Blog provider that we configured. The next section we need to modify is the http method and url. At this point we need to consult the API documentation to identify what we should put in here. We want data from the incident table in ServiceNow and, looking at the documentation, we can see that we need to make a GET request to the Base URL + now/table/incident:

In our http mode tile panel, we need to make sure that get is selected and then append the required URL text to our pre-populated base URL:

The next step is to specify some ServiceNow-specific URL parameters:

The net effect of these parameters is to request a maximum of 20 incident records that are in an Active state. For these records, I’m only asking for a specific subset of column values (as defined in the sysparm_fields parameter). Lastly the sysparm_display_value parameter ensures that ServiceNow returns the actual display value of properties like the assigned user or affected server, rather than another API URL to retrieve these display values.

These options are within the data section of the Headers and Data panel, which means they will be URL parameters when the API request is made by SquaredUp. Here’s an example of how this would look in the resulting URL:

/api/now/table/incident?sysparm_fields=sys_id%2curgency%2ccmdb_ci%2cshort_description%2cseverity%2cstate%2cassigned_to&sysparm_limit=20&sysparm_query=active&sysparm_display_value=true

OK. We’ve set the method to GET and put the URL in as the documentation specified, and we’ve also configured some URL parameters and values in the data section to modify what results ServiceNow returns. Let’s click Next and see what we get.

Hmm. That doesn’t look great. We’ve got one column called result and a whole load of [object Object] entries. Weird.

The reason we have this unexpected result is that there’s some nesting going on in the JSON response from ServiceNow. We need to tell SquaredUp where the data we want is within the response. The fact that we have a column name called result in our tile is a clue, but we can confirm our suspicions by intercepting the server’s response with our HTTP capture utility.

As in our example, the JSON object has a single key called result that contains other JSON objects, each made up of its own keys and values.

Let’s move on to the response data panel in the Web API Tile configuration and put result in here:

That’s more like it. At least the results are mostly readable, but annoyingly the assigned_to column has got [object Object] for some of the entries.

Looking at our HTTP capture response again, we can see why: assigned_to contains another JSON object as its value, so we need to specify the display_value key within this object to get the user’s name. We can do this within the grid columns panel in our tile configuration.

We’re going to use a custom template on the assigned_to column to do this. Clicking edit then clicking the curly braces button displays the properties of the assigned_to JSON object. This shows the display_value and link properties in this object, so it turns out we don’t need an HTTP capture tool to find the information we need; SquaredUp will display the keys and values in nested JSON objects to help us select the right one.

Clicking value.display_value in the drop down list then automatically populates the custom template field for the column:

This tells SquaredUp that, for the assigned_to column, it should display the text associated with display_value rather than the entire assigned_to value (which is a JSON object, hence [object Object]).

The result for the Assigned To column now looks how we would expect it to look:

Now, to be honest, we could have avoided having to do this column configuration by specifying the sysparm_exclude_reference_link parameter and setting its value to true in our headers and data tile panel. With this in place, the assigned_to result would simply be the name of the user, rather than a JSON object containing other properties and values. However, you might need to connect to an API that doesn’t provide this as an option, so it’s useful to know how to edit columns to return the value that is of interest to you when a JSON object is returned.

The SquaredUp Web API tile can also use context to affect what data is returned from a given API. If we either set a scope on a dashboard Web API tile or create our tile on a perspective rather than a dashboard, then we can insert dynamic values into the headers & data tile panel. As an example, I’ve created a Web API tile on a perspective and I’m querying the cmdb_ci table in my tile to get server information from ServiceNow.

In my sysparm_query parameter for this tile, I’ve used the mustache editor to define the value of the name property:

SquaredUp will therefore automatically populate the sysparm_query parameter with the NETBIOS name of whatever server the perspective is running on. As such, we can create a perspective once and have it display the right data for whatever server we happen to be looking at in SquaredUp. The result in my example tile now displays ServiceNow information on this server:

As you can see, the standardised nature of REST APIs together with SquaredUp’s ability to integrate with these APIs opens up plenty of potential use cases when it comes to monitoring your IT systems.

If you’re interested in finding out more about what SquaredUp can do with other services like Splunk and New Relic amongst others, check out our integrations webinar on the SquaredUp YouTube channel. Our Knowledge Base also has some great walk-through examples of using the Web API tile for Splunk, ServiceNow and Google Analytics along with Azure Log Analytics and Azure App Insights.

If you come across a particularly tricky API and things don’t quite go to plan when trying to get your Web API providers and tiles configured in SquaredUp then we’d be happy to help out. Just raise a support ticket via our web site and our support team will take a look. We also have a really knowledgeable SquaredUp Community that can help out too!