rest-integration

ServiceNow provides RESTMessageV2 for outbound REST API calls and the REST API for inbound requests.

Outbound REST (Calling External APIs)

Basic GET Request

var request = new sn_ws.RESTMessageV2();
request.setEndpoint('https://api.example.com/users');
request.setHttpMethod('GET');
request.setRequestHeader('Accept', 'application/json');

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

if (httpStatus == 200) {
  var data = JSON.parse(body);
  gs.info('Found ' + data.length + ' users');
}

POST Request with JSON Body

var request = new sn_ws.RESTMessageV2();
request.setEndpoint('https://api.example.com/incidents');
request.setHttpMethod('POST');
request.setRequestHeader('Content-Type', 'application/json');
request.setRequestHeader('Accept', 'application/json');

var payload = {
  title: 'New Incident',
  description: 'Created from ServiceNow',
  priority: 'high'
};
request.setRequestBody(JSON.stringify(payload));

var response = request.execute();

Using REST Message Records

Create a REST Message record for reusable integrations:

// Using predefined REST Message from sys_rest_message
var request = new sn_ws.RESTMessageV2('External API', 'Create User');

// Set variable substitutions defined in the REST Message
request.setStringParameter('user_name', userName);
request.setStringParameter('email', email);

var response = request.execute();

Authentication Methods

Basic Authentication

var request = new sn_ws.RESTMessageV2();
request.setEndpoint('https://api.example.com/data');
request.setHttpMethod('GET');
request.setBasicAuth('username', 'password');

Bearer Token

var request = new sn_ws.RESTMessageV2();
request.setEndpoint('https://api.example.com/data');
request.setHttpMethod('GET');
request.setRequestHeader('Authorization', 'Bearer ' + token);

OAuth 2.0 (Using OAuth Profile)

var request = new sn_ws.RESTMessageV2();
request.setEndpoint('https://api.example.com/data');
request.setHttpMethod('GET');
request.setAuthenticationProfile('oauth2', 'My OAuth Profile');

API Key

var request = new sn_ws.RESTMessageV2();
request.setEndpoint('https://api.example.com/data');
request.setHttpMethod('GET');
request.setRequestHeader('X-API-Key', apiKey);
// Or as query parameter
request.setQueryParameter('api_key', apiKey);

Error Handling

try {
  var request = new sn_ws.RESTMessageV2();
  request.setEndpoint('https://api.example.com/data');
  request.setHttpMethod('GET');
  request.setHttpTimeout(10000);  // 10 second timeout

  var response = request.execute();
  var httpStatus = response.getStatusCode();

  if (httpStatus == 200) {
    var body = response.getBody();
    var data = JSON.parse(body);
    // Process successful response
  } else if (httpStatus == 401) {
    gs.error('Authentication failed');
  } else if (httpStatus == 404) {
    gs.error('Resource not found');
  } else if (httpStatus >= 500) {
    gs.error('Server error: ' + httpStatus);
  } else {
    gs.error('Unexpected status: ' + httpStatus);
  }
} catch (ex) {
  gs.error('REST Exception: ' + ex.message);
}

Response Handling

Parse JSON Response

var body = response.getBody();
var data = JSON.parse(body);

// Access nested data
var userName = data.user.name;
var items = data.items || [];

Handle Arrays

var body = response.getBody();
var users = JSON.parse(body);

for (var i = 0; i < users.length; i++) {
  var user = users[i];
  gs.info('User: ' + user.name + ' (' + user.email + ')');
}

Response Headers

var contentType = response.getHeader('Content-Type');
var rateLimitRemaining = response.getHeader('X-RateLimit-Remaining');

MCP Tools for REST

// Create REST Message record
snow_create_rest_message({
  name: "External API",
  endpoint: "https://api.example.com",
  authentication: "basic",  // or "oauth2", "api_key"
  methods: [
    {
      name: "Get Users",
      http_method: "GET",
      endpoint: "/users"
    },
    {
      name: "Create User",
      http_method: "POST",
      endpoint: "/users",
      content_type: "application/json"
    }
  ]
});

// Test REST connection
snow_test_rest_connection({
  endpoint: "https://api.example.com/health"
});

Best Practices

• Use REST Message records - Centralized configuration, easier maintenance

• Set timeouts - Prevent hanging scripts with setHttpTimeout()

• Handle all status codes - Not just 200

• Log failures - Use gs.error() for debugging

• Use Async for slow APIs - Don't block business rules

• Store credentials securely - Use Connection & Credential Aliases

• Implement retry logic - For transient failures

• Rate limit awareness - Check response headers, implement backoff

Retry Pattern

function callApiWithRetry(endpoint, maxRetries) {
  var retries = 0;
  var delay = 1000;  // Start with 1 second

  while (retries < maxRetries) {
    try {
      var request = new sn_ws.RESTMessageV2();
      request.setEndpoint(endpoint);
      request.setHttpMethod('GET');

      var response = request.execute();

      if (response.getStatusCode() == 200) {
        return JSON.parse(response.getBody());
      }

      if (response.getStatusCode() >= 500) {
        // Server error - retry
        retries++;
        gs.sleep(delay);
        delay = delay * 2;  // Exponential backoff
        continue;
      }

      // Client error - don't retry
      throw new Error('Client error: ' + response.getStatusCode());

    } catch (ex) {
      retries++;
      if (retries >= maxRetries) {
        throw ex;
      }
      gs.sleep(delay);
      delay = delay * 2;
    }
  }
}