Create a Scripted REST API endpoint

Server-sideadvancedTested on Xanadu

Chrome Extension

Sourdough: ServiceNow Monitoring and Analytics

A Chrome extension for ServiceNow Admins and Developers with essential tools, analytics, graphs and monitoring features.

Instance HealthGraphs & ChartsAPI HealthDeveloper ToolsQuick SearchInstance Switcher

Add to Chrome

Free to install. Pro $5/month after a 14-day no-card trial.
Pro requires the ServiceNow admin role. Upgrade inside the extension.

Overview

Tasks

CMDB

API

Metrics

Monitor

Internals

Instance:sourdoughdev·Version:Yokohama

Instance StateONLINE

System StatusFully Operational

Session Timeout90 minutes

Logged-In Sessions2 (20 active)

Build Nameyokohama-12-18-2024_p1

IP Address10.159.128.43

Instance HealthHealth Score: 90%

🔥 5dSourdough (Chrome Plugin)Dark Mode

Define a custom REST API endpoint that returns JSON data

Scripted REST API

(function process(request, response) {
    var pathParams = request.pathParams;
    var queryParams = request.queryParams;
    var requestBody = request.body;
    
    // Validate required path parameter
    if (!pathParams.incident_number) {
        response.setStatus(400);
        response.setHeader('Content-Type', 'application/json');
        var errorResponse = {
            error: 'Missing required parameter: incident_number',
            status: 400
        };
        response.getStreamWriter().writeString(JSON.stringify(errorResponse));
        return;
    }
    
    var gr = new GlideRecord('incident');
    gr.addQuery('number', pathParams.incident_number);
    gr.setLimit(1);
    gr.query();
    
    if (!gr.next()) {
        response.setStatus(404);
        response.setHeader('Content-Type', 'application/json');
        var notFoundResponse = {
            error: 'Incident not found',
            incident_number: pathParams.incident_number,
            status: 404
        };
        response.getStreamWriter().writeString(JSON.stringify(notFoundResponse));
        return;
    }
    
    // Include comments only if requested to avoid unnecessary queries
    var includeComments = queryParams.include_comments === 'true';
    var responseData = {
        sys_id: gr.getUniqueValue(),
        number: gr.getValue('number'),
        state: gr.getValue('state'),
        state_label: gr.getDisplayValue('state'),
        short_description: gr.getValue('short_description'),
        priority: gr.getValue('priority'),
        assigned_to: gr.getDisplayValue('assigned_to'),
        opened_at: gr.getValue('opened_at')
    };
    
    if (includeComments) {
        var commentGr = new GlideRecord('sys_journal_field');
        commentGr.addQuery('element_id', gr.getUniqueValue());
        commentGr.addQuery('element', 'comments');
        commentGr.orderByDesc('sys_created_on');
        commentGr.query();
        
        responseData.comments = [];
        while (commentGr.next()) {
            responseData.comments.push({
                value: commentGr.getValue('value'),
                created_on: commentGr.getValue('sys_created_on'),
                created_by: commentGr.getDisplayValue('sys_created_by')
            });
        }
    }
    
    response.setStatus(200);
    response.setHeader('Content-Type', 'application/json');
    response.getStreamWriter().writeString(JSON.stringify(responseData));
    
})(request, response);

ServiceNow's Scripted REST APIs follow a specific pattern that trips up developers coming from other platforms. The request and response objects are injected into the execution context, but unlike Express.js or similar frameworks, you must explicitly set headers and use getStreamWriter() to write response bodies. The biggest mistake developers make is assuming path parameters are automatically parsed as the correct data types—they're always strings and require explicit validation.

When to use Scripted REST APIs

When you need custom business logic that the Table API doesn't support
When integrating with external systems that require specific response formats
When you need to aggregate data from multiple tables in a single request
When you need custom authentication or authorization logic beyond ACLs

When NOT to use Scripted REST APIs

Don't use for simple CRUD operations—use the Table API instead
Don't use for high-volume operations without pagination—you'll hit execution limits
Don't use for file uploads/downloads—use Attachment API or custom processors
Don't use for real-time notifications—use Server-Sent Events or WebSocket endpoints

Key behaviors and gotchas

Path parameters in request.pathParams are always strings, even numeric-looking values
You must explicitly call response.setHeader('Content-Type', 'application/json') or responses default to text/plain
Request body parsing depends on Content-Type header—JSON isn't automatically parsed
ACLs still apply to GlideRecord queries within the API—scope doesn't bypass security
The API inherits the application scope it's defined in—cross-scope table access requires explicit permissions
Execution time limit is 60 seconds—long-running operations will timeout

⚠️

Always validate path parameters exist before using them. ServiceNow doesn't return 404 for missing path params—your script will execute with undefined values, leading to confusing errors or unintended behavior.

Free Newsletter

Enjoying this? Get one deep-dive per week.

Join 1,000+ ServiceNow pros — scripts, GlideRecord patterns, Flow Designer techniques, and career moves. Free.

Alternative Approaches

Table API with Business Rules

// Business Rule on incident table (before query)
if (gs.getProperty('incident.api.enhanced_response', 'false') === 'true') {
    // Add custom fields to response
    current.u_api_response_enhanced = 'true';
}

Use when you need to modify standard Table API responses with custom logic.

Trade-offs: Less flexible than Scripted REST but leverages existing Table API infrastructure and caching.

API Methods Used

GlideRecord.addQuery()GlideRecord.setLimit()GlideRecord.getValue()GlideRecord.getDisplayValue()

Test Your Knowledge

Quick 3-question quiz — see how your ServiceNow skills stack up.

Question 1 of 3Performance

A list view on a table with millions of records is slow. Best fix?

Select an answer to continue