ServiceNow Scripted REST

You are a ServiceNow integration developer. The user wants to build Scripted REST APIs with complete request/response handling, including parameter parsing, authentication, and error management.

What to check first

• Verify you have admin or developer role in your ServiceNow instance to create Scripted REST APIs
• Check that the REST API plugin is activated: Navigate to System Plugins and search for "REST API"
• Confirm your ServiceNow version supports Scripted REST (all current versions do, but verify in System Information)

Steps

1. Navigate to System Web Services > Scripted REST APIs and click New to create a new API resource
2. Set the API ID (e.g., my_custom_api) and API Version (typically 1), which creates the base endpoint path /api/sn_custom_api/my_custom_api/v1
3. Under the API record, create a Resource by clicking New in the Resource section—set the Resource path (e.g., users creates /api/sn_custom_api/my_custom_api/v1/users)
4. On the Resource record, create Methods (GET, POST, PUT, DELETE) by clicking New in the Methods section
5. In each Method record, write your handler script in the Script field—this is where request and response objects are available automatically
6. Access request.body (parsed JSON), request.queryString, request.pathParams, and request.headers to extract incoming data
7. Build responses using response.setStatus(httpCode), response.setContentType('application/json'), and response.setBody(JSON.stringify(data))
8. Test the endpoint using the Test button in the Method record or external tools like Postman pointing to your instance URL

Code

(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
  try {
    var method = request.getMethod();
    var pathParams = request.pathParams;
    var queryParams = request.queryString;
    var body = {};
    
    // Parse request body safely
    if (request.body && request.body !== '') {
      try {
        body = JSON.parse(request.body);
      } catch (e) {
        response.setStatus(400);
        response.setBody(JSON.stringify({
          error: 'Invalid JSON in request body',
          message: e.message
        }));
        return;
      }
    }
    
    // Route based on HTTP method
    if (method === 'GET') {
      // Handle GET: fetch user by ID from path param
      var userId = pathParams.user_id;
      if (!userId) {
        response.setStatus(400);
        response.setBody(JSON.stringify({ error: 'user_id path parameter required' }));
        return;
      }

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change