REST

Sending REST

Jace Benson

Table of content
  1. RESTMessageV2
  2. Authentication
  3. Mutual Auth (mTLS)
  4. Running on a MID Server
  5. Advanced Features
  6. RESTMessageV2 vs RESTMessageV1
  7. Scripted REST Messages (Outbound)
  8. Additional Resources

Docs

RESTMessageV2 is how you make outbound REST calls from ServiceNow. It handles the HTTP layer — method, headers, auth, body — and returns the response so you can parse it.

RESTMessageV2

The API is straightforward: create a message, set the endpoint, configure auth, send it.

var request = new sn_ws.RESTMessageV2();
request.setEndpoint('https://api.example.com/v1/data');
request.setHttpMethod('POST');
request.setRequestHeader('Content-Type', 'application/json');
request.setRequestBody(JSON.stringify({ key: 'value' }));

var response = request.execute();
var body = response.getBody();
var status = response.getStatusCode();

Authentication

RESTMessageV2 supports basic auth, OAuth, mutual auth, and key-based auth. You can hard-code credentials or use an authentication profile.

// Basic auth
request.setBasicAuth('username', 'password');

// OAuth — uses an OAuth entity profile
request.setAuthenticationProfile('my_oauth_profile', 'oauth_token');

Mutual Auth (mTLS)

For mutual authentication, you bind a certificate to the REST message. The MID Server handles the cert at runtime.

request.setMutualAuth('My Certificate Profile');

Running on a MID Server

If your target is internal (not reachable from the instance), route through a MID Server.

request.setMIDServer('mid-server-name');
request.setHttpTimeout(30000); // 30 second timeout on the MID

Advanced Features

RESTMessageV2 vs RESTMessageV1

Always use RESTMessageV2. The V1 API (RESTMessageV1) is deprecated and doesn't support OAuth, mutual auth, or MID Server routing properly.

Scripted REST Messages (Outbound)

You can define REST messages in sys_rest_message and sys_rest_message_fn tables, then call them by name. This is useful when you have multiple scripts hitting the same endpoint — define it once, reference it everywhere.

var request = new sn_ws.RESTMessageV2('my_message', 'my_function');
var response = request.execute();

Additional Resources