ServiceNow’s JSON Web Service interface 1 / 3

Foreword

The ServiceNow platform provides a number of integration functionalities which can be used to glue a ServiceNow instance and any 3rd party software together. One of the less known, and certainly less used, integration interfaces provided by the ServiceNow platform is the JSON Web Service interface.

The reason for the low adoption rate can probably be attributed to popularity of the SOAP over HTTP in the enterprise software industry and to the fact that the “JSON Web Service” plugin is not active by default on Out-of-the-Box ServiceNow instances.



When should one use the JSON Web Service in an integration between ServiceNow platform and a 3rd party system? In most situations where you would otherwise use the Direct Web Services and the 3rd party system is able to handle the JSON format. The JSON format is significantly more compact and hence uses significantly less bandwidth in request and response messages. Therefore, the attractiveness of the JSON interface is directly proportional to the amount of transactions and inversely proportional to available bandwidth.

In this post, and in the following two blog posts, I would like to introduce to you the ServiceNow’s JSON Web Service. The breakdown by content of the blog posts is as follows

1. (this) Quick introduction to JSON and the ServiceNow’s JSON Web Service’s functionality in general
2. Data Retrieval functionality
3. Data Modification functionality

JSON

JSON, or JavaScript Object Notation, is a text-based human-readable data interchange format. In JSON, an object is enclosed within curly brackets, an array within brackets and variable name and value pairs are described in “<variable_name>”:<value> format. Member variables are separated by commas. An example can be seen below where

• A represents an object
• B represents an array variable named “records” containing an object
• C block shows two member variables of an object, separated by a comma

The above example is enough for the purpose of this blog post, but the full introduction to JSON format is available at http://www.json.org/

JSON versus SOAP

JSON is a human-readable format, like SOAP (XML), but JSON contains less metadata and is generally considered to be faster to parse. As an example, let us compare web service call fetching a single Incident record from an Out-of-the-Box ServiceNow instance

• the request message for Direct Web Service is 301 bytes as the request message defines the requested resource
• the response message from Direct Web Services is 1117 bytes

AND

• the request message for JSON Web Service is 0 bytes as the URL defines the requested resource
• the response message from JSON Web Service is 863 bytes.

In this use case the JSON is roughly 39% lighter. Once we factor in the overhead caused by HTTP, the percentage obviously drops. Following picture displays the shortened response messages side by side for comparison.



The steps taken to retrieve the JSON response from a ServiceNow instance will be covered in the second installment of this blog series.

JSON Web Service interface

The ServiceNow platform’s JSON Web Service provides the same actions for reading and modifying data as the Direct Web Services. This means you will be able to create, read, update and delete any record in a ServiceNow instance. Just like the Direct Web Service interface, the JSON Web Service interface automatically provides an interface for any OOB tables and custom tables created to a ServiceNow instance. Breakdown of the available actions is presented below.

Data Retrieval actions:

• get : get an individual record
• getKeys : get the sys_id’s of records matching the query
• getRecords : get the records matching the query

Data Modification actions:

• insert : insert a new record
• insertMultiple : insert multiple new records
• update : update a record
• deleteRecord : delete a record
• deleteMultiple : delete records matching the query

Security

Like the Direct Web Service interface, the JSON Web Service interface requires the callers to identify themselves using basic authentication. Similarly, the calls made via the JSON Web Service are subject to the same Access Control settings as calls made via the Direct Web Service. The impact of this is that the user credentials provided to the integration partner must have any roles required to create, read, update and delete a record via the UI.

Next

In the next installment of this blog series I will be covering the Data Retrieval functionality of the ServiceNow platform’s JSON Web Service interface.