Inbound REST Integrations

Inbound REST Integrations

Inbound REST Integrations in ServiceNow Objectives

In these docs, you will:

• Explore the REST API Explorer and Table API to interact with ServiceNow table
records, covering:
o Path parameters
o Query parameters
o Headers
o HTTP Status codes
o Response bodies
• Set up a ServiceNow user for inbound REST requests
• Define Cross-Origin Resource Sharing (CORS) rules to control allowed HTTP methods
from a resource
• Restrict web service access to specific tables
• Develop code samples for seamless integration of third-party applications with
ServiceNow

Saurav Kumar Jha

Inbound REST Integrations

ServiceNow as a Web Service Provider

ServiceNow acts as a web service provider, enabling applications to connect and exchange
data over a network. The consumer (client) sends requests, and the provider (server)
processes them, returning a status code and response body. The client then extracts
relevant data and takes action accordingly.

In an inbound request, a third-party application requests an action through a ServiceNow

API. Example ServiceNow APIs include:

• Table API: Create, read, update, and delete records from a table
• Attachment API: Upload and query file attachments
• Email API: Send and receive email messages using REST

Saurav Kumar Jha

Inbound REST Integrations

Introduction to the REST API Explorer

To integrate with a web service, developers must understand:

• Endpoints
• Methods
• Variables

ServiceNow's REST API Explorer allows users to construct and test API requests within a
ServiceNow instance. It is accessible to those with the rest_api_explorer or admin role. To
open it, navigate to System Web Services > REST > REST API Explorer via the All menu.

The REST API Explorer includes:

• A pane to select Namespace, API Name, API Version, and REST method
• A pane to view and configure the endpoint
• A menu for API documentation and an API analytics dashboard
• A section to test the endpoint (not shown in the image)

Saurav Kumar Jha

Inbound REST Integrations

Selecting an API

The fields in the Prepare request section of the REST API Explorer form are determined by
which Namespace, API Name, API Version, and REST method is selected.

• Namespace: Select the web service scope

o global: Globally scoped APIs
o now: REST APIs provided by ServiceNow
o private_scope_name: Namespace format used for APIs (scripted web
services) in privately-scoped applications
• API Name: Select an API to configure and test in the REST API Explorer
• API Version: Select a specific API version or choose latest
• Method: Select from the list of available REST methods based on
the Namespace, API Name, and API Version. The arrowhead indicates the selected
method.

• For the Aggregate API, only one method is available.

The REST API Explorer displays information about the selection. For more information,
select the API documentation menu item from the REST API Explorer menu.

Saurav Kumar Jha

Inbound REST Integrations

Request Parameters

Request Parameters consist of:

• Path parameters
• Query parameters
• Request headers

Path Parameters

Path parameters vary based on the endpoint URL and are enclosed in curly braces {}.
When a request is sent, the values entered in the path parameter field replace the
placeholders in the URL.

Saurav Kumar Jha

Inbound REST Integrations

Query Parameters

The REST API Explorer adds request parameters to the endpoint URL when sending a
request. Query parameters are specific to the selected API method.

The API displays a default set of query parameters. To add more, click Add query
parameter. For a full list and details, access the API documentation from the REST API
Explorer menu.

Saurav Kumar Jha

Inbound REST Integrations

Request Headers

Request headers define the format of the Request and Response.

Use the Add header button to add additional headers to the request. For the ServiceNow
APIs, two useful additional header parameters are:

• X-WantSessionNotificationMessages: Set to true to return notifications that have

not already been consumed for the existing session.
• X-WantSessionDebugMessages: Enable Session Debug and set the header value
to true to return session debug logs.

Saurav Kumar Jha

Inbound REST Integrations

More About Query Parameters

Query parameters may contain different types of values, such as:

• Encoded queries
• Field name(s)
• true/false/all

Encoded Queries

Certain query parameters, like sysparm_query and sysparm_having, accept encoded

queries, which are difficult to create manually and not documented. Let ServiceNow
generate them instead:

1. In the ServiceNow browser, open the table list via the All menu.
o If no module exists, type .list in the Filter navigator.
2. Use the Filter to build the query condition.

Click the Run button to execute the query. Right-click the breadcrumbs and select Copy
query.

NOTE: The copied query includes the condition right-clicked on and all conditions to the
left. To copy the entire query, right-click <the condition farthest to the right>.

Return to the REST API Explorer and paste the encoded query into the query parameter.

Saurav Kumar Jha

Inbound REST Integrations

Field Names

Some query parameters, such as sysparm_group_by, accept a field name or a comma

separated list of field names. Developers must pass the field name not the field label.

To select fields from a slushbucket, click the Edit button (

) on the field.

Dot-walking is allowed in field names, for example, caller_id.title.

true/false/all

When a REST call returns a reference field from a table, developers can select the format
for the returned value.

• Set the value to true to return the display value

• Set the value to false to return the sys_id
• Set the value to all to return both the display value and the sys_id

Saurav Kumar Jha

Inbound REST Integrations

Testing

After configuring the REST method, click the Send button to send the request to the API.

The REST API Explorer responds as if the request came from a third party application:

• Request
• Response
• Response Body

Saurav Kumar Jha

Inbound REST Integrations

Saurav Kumar Jha

Inbound REST Integrations

ServiceNow API Request

The REST API Explorer constructs the request to send to the ServiceNow API using the
settings configured by the developer.

Path Parameters in the Request

The Request section displays the HTTP Method / URI to send to the ServiceNow web
service. The method is from the selected API. The path parameter values are set when
configuring the request.

Saurav Kumar Jha

Inbound REST Integrations

Query Parameters in the Request

The query parameters are added to the URI. In the example shown, the URI is truncated
due to space limitations. To see the complete URI in the REST API Explorer, scroll
horizontally.

Saurav Kumar Jha

Inbound REST Integrations

Headers in the Request

REST headers are the meta-data associated with an API request and response. The
Request Header settings appear in the request.

__________________________________________________________________________

ServiceNow API Response

The ServiceNow API Response consists of:

• HTTP status code

• Response headers
• Response body

HTTP Status Code

ServiceNow APIs return standard HTTP status codes. Generally speaking:

• 1xx: Informational
• 2xx: Success
• 3xx: Redirection
• 4xx: Client Error
• 5xx: Server Error

Saurav Kumar Jha

Inbound REST Integrations

The HTTP status codes refer to the interaction with the REST service provider. The status
codes do not tell anything about the requested data. The REST transaction request can
complete successfully even if no data is returned.

Saurav Kumar Jha

Inbound REST Integrations

Response Headers

The Headers section shows the returned headers and their values.

Response Body

The response body is the data object returned by the ServiceNow web service provider.
The response body varies depending on the selected API. In the example, the Aggregate
API returns the count of open incident records in the past year with a priority
of Critical or High. The results are grouped by the user in the Assigned to field.

Saurav Kumar Jha

Inbound REST Integrations

Beth Anglin has three Critical or High priority incidents still open from the past year.
Notice in this case both the value (sys_id) and display_value are included for
the assigned_to field.

Data Types and Returned Values

• Encrypted text: The database value is encrypted, while the displayed value is
unencrypted based on the user's encryption context.
• Reference fields: The database value is a sys_id and the display value is the human
readable name.
• Date fields: The database value is in UTC format, while the display value is based
on the user's time zone.
• Choice fields: The database value may be a number, while the display value will be
more descriptive.
• Currency fields: When performing a REST request, returned currency values are
converted to local currency based on the user’s locale. When inserting data, no
conversion is performed.

-----------------------------------------------------------------------------------------------------------------------

Adding Security to Inbound Requests

Strategies to add security to inbound API requests include:

• Create a user specifically for inbound requests

• Disallow web service access to tables
• Create CORS rules

Saurav Kumar Jha

Inbound REST Integrations

Create an API Request User

Users with the Web service access only option set on their user record cannot log into the
ServiceNow UI. This option allows the user credentials to be used only to authorize API
connections. To set this option, open the user record for editing using the User
Administration > Users module.

The API request user must be granted the roles necessary to access the records requested
by the API requests.

Saurav Kumar Jha

Inbound REST Integrations

Disallow Web Service Access to Tables

Administrators can disable web service access to tables. On the table record, open
the Application Access section and de-select the Allow access to this table via web
services option. REST requests are not accepted for tables unless this option is selected
(checked). To set this option, open the table record for editing using the System Definition
> Tables module.

CORS Rules

Cross-Origin Resource Sharing (CORS) rules control which domains can access specific
REST API endpoints. To create a CORS rule, use the All menu to open System Web Services
> REST > CORS Rules.

In the example, the resource https://www.test-cors.org can only access the Table
API using the GET method.

• REST API: The REST API the CORS rule applies to.
• Domain: The domain for the CORS rule. Specify the domain using an IP Address or
a domain pattern.

Saurav Kumar Jha

Inbound REST Integrations

• Max age: The number of seconds to cache the client session. After an initial CORS
request, further requests from the same client within the specified time do not
require a preflight message. If a value is not specified, the default value of 0
indicates that all requests require a preflight message.
• HTTP Methods: The methods allowed.
• HTTP Headers: A comma-separated list of HTTP headers to send in the response.
Specified headers are added to the Access-Control-Expose-Headers header.

There are a number of requirements for specifying the domain including:

• Start with http:// or https://

• Must be an IP address or domain pattern
• Can contain only one wildcard *

-----------------------------------------------------------------------------------------------------------------------

Code Samples

The REST API Explorer creates code samples for integrating with the ServiceNow APIs in
several commonly used languages:

• ServiceNow Script
• cURL
• Python
• Ruby
• JavaScript
• Perl
• Powershell

To create the code sample, click the link in the REST API Explorer.

To highlight the code sample for copying, click the Select Snippet button.

Saurav Kumar Jha

Inbound REST Integrations

After highlighting the code sample, copy the code sample to the clipboard.

All code samples use fake credentials. Before using the script in the application to
integrate with ServiceNow, update the code to use valid credentials.

-----------------------------------------------------------------------------------------------------------------------

Saurav Kumar Jha

Inbound REST Integrations

Inbound Integrations Module Recap

Core concepts:

• Use the REST API Explorer to create and test inbound ServiceNow API requests
• Path parameters are part of the endpoint URL
• Query parameters determine which records, which data, and the data format
returned in the response body
• The HTTP status code indicates the status of the transaction request and does not
indicate any information about the returned data
• The response body format is set in the headers
• The REST API Explorer tests requests as the currently logged in user
• The Allow access to this table via web services option cannot be tested in the REST
API Explorer
• Do not use the admin user in code integrations, create a web services only user
instead
• Disable web service access to tables with sensitive data unless web service access
is required
• CORS rules add security to APIs
o CORS rules determine which cross-origin resources can access which
methods
o CORS rules cannot be tested in the REST API Explorer
• Code samples provide script stubs for integrating into ServiceNow from third party
applications
o Developers must update credentials in the code samples
o Code samples are available in multiple standard languages used with
integrations

Saurav Kumar Jha