Integrating with REST

What it is

REST lets your application exchange data with another system over HTTP, usually as JSON. ServiceNow works in both directions. Outbound, the instance calls an external API, for example to fetch a weather forecast. Inbound, an external system calls the instance, through the Table API or a Scripted REST API that you build.

For the exam you need to know which record to create, how to call it from script, how to test it and where to look when it fails.

How it works

Outbound: REST Message records

An outbound call is defined as a REST Message under System Web Services > Outbound > REST Message. The REST Message holds the base endpoint and the authentication, such as a basic auth profile or an OAuth 2.0 profile. Each HTTP Method record below it (GET, POST, PUT, PATCH, DELETE) holds its own endpoint, headers, query parameters and request body.

Endpoints and bodies can contain variables written as ${name}, which a script fills at run time. The Test related link on an HTTP Method sends the request and shows the status code and response body. Preview Script Usage shows ready-made RESTMessageV2 code for that method.

For an endpoint inside a private network, the request can be sent through a MID Server instead of straight from the instance.

Outbound: calling it from script

var r = new sn_ws.RESTMessageV2('Weather API', 'Get forecast');
r.setStringParameterNoEscape('city', current.getValue('u_city'));
var response = r.execute();
if (response.getStatusCode() == 200) {
  var data = JSON.parse(response.getBody());
  current.u_forecast = data.summary;
}

execute() waits for the answer. executeAsync() returns at once, which suits slow APIs, and waitForResponse() can be called later if the answer is needed. Avoid long synchronous calls in a before business rule, where the user waits for the save.

Inbound: Table API and REST API Explorer

The Table API exposes records at /api/now/table/<table name> with GET, POST, PUT, PATCH and DELETE. Every call runs as the authenticated user, so normal ACLs decide what that user may read or change.

The REST API Explorer (System Web Services > REST > REST API Explorer) builds and sends test requests to the instance's own APIs and shows the request URL, headers, response and sample code. It needs the rest_api_explorer, web_service_admin or admin role. It tests inbound APIs; it does not test outbound REST Messages.

Inbound: Scripted REST APIs

When the Table API does not fit, for example you want one call to return data from several tables, build a Scripted REST API under System Web Services > Scripted REST APIs. Its base path is built from the application namespace and the API ID. Each resource has an HTTP method, a relative path such as /order/{id} and a script.

(function process(request, response) {
  var gr = new GlideRecord('x_acme_orders_order');
  if (!gr.get(request.pathParams.id)) {
    response.setStatus(404);
    return;
  }
  response.setBody({ number: gr.getValue('number'), state: gr.getValue('state') });
})(request, response);

request.pathParams, request.queryParams and request.body.data carry the input. Resources require authentication by default and can be protected by REST ACLs.

Status codes to recognize

Testing and debugging

For outbound calls, open System Logs > Outbound HTTP Requests to see each request, endpoint, status and timing; the HTTP log level on the REST Message or HTTP Method controls how much detail is kept. In script, log getStatusCode(), getBody() and getErrorMessage(). For inbound calls, reproduce the request in the REST API Explorer, then check ACLs and the system log.

How the exam asks about this

• "Store the endpoint and credentials once and call them from several scripts." Create a REST Message with HTTP Methods and call it with RESTMessageV2.
• "An integration user gets 403 calling a Scripted REST resource." The user is authenticated but fails the ACL; grant the needed role.
• "Return combined data from two tables in a single call." Build a Scripted REST API resource.