Inbound API Rate Limiting Pattern for…

advancedTested on Xanadu

The Inbound API Rate Limiting pattern protects ServiceNow scripted REST APIs from excessive requests that could degrade system performance or indicate malicious activity. This pattern uses GlideCache to maintain request counters per client identifier (IP address, API key, or user) within defined time windows.

When request limits are exceeded, the API returns HTTP 429 Too Many Requests responses with appropriate Retry-After headers, giving legitimate clients guidance on when to retry. The pattern also logs potential abuse attempts for security monitoring and can be configured with different limits for different API endpoints or client types.

The implementation leverages ServiceNow's distributed cache system to ensure rate limits work consistently across multiple application nodes in clustered environments, making it suitable for high-availability production systems.

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

Use This When

Use this pattern when exposing public-facing or high-volume REST APIs that need protection from abuse, DoS attacks, or runaway client applications. It's essential for APIs that perform expensive operations, access sensitive data, or integrate with external systems that have their own rate limits.

Avoid When

Avoid this pattern for internal APIs with trusted clients where the overhead isn't justified, or when ServiceNow's native web service access controls and IP restrictions provide sufficient protection. Don't implement this for low-volume APIs or when you need more sophisticated throttling policies that require persistent storage beyond simple request counting.

Implementation

Server-side

// Script Include: RateLimitManager
var RateLimitManager = Class.create();
RateLimitManager.prototype = {
    initialize: function() {
        this.cache = new GlideCache('RateLimit');
        this.defaultWindowSecs = 3600; // 1 hour
        this.defaultMaxRequests = 1000;
    },

    isRateLimited: function(clientId, endpoint, maxRequests, windowSecs) {
        maxRequests = maxRequests || this.defaultMaxRequests;
        windowSecs = windowSecs || this.defaultWindowSecs;
        
        var cacheKey = clientId + ':' + endpoint + ':' + this._getCurrentWindow(windowSecs);
        var currentCount = parseInt(this.cache.get(cacheKey) || '0');
        
        if (currentCount >= maxRequests) {
            gs.warn('Rate limit exceeded for client: ' + clientId + ', endpoint: ' + endpoint + ', count: ' + currentCount);
            return {
                limited: true,
                retryAfter: this._getRetryAfter(windowSecs),
                currentCount: currentCount,
                maxRequests: maxRequests
            };
        }
        
        // Increment counter
        this.cache.put(cacheKey, (currentCount + 1).toString(), windowSecs);
        
        return {
            limited: false,
            currentCount: currentCount + 1,
            maxRequests: maxRequests,
            remaining: maxRequests - (currentCount + 1)
        };
    },
    
    _getCurrentWindow: function(windowSecs) {
        var now = new GlideDateTime();
        var epochSecs = Math.floor(now.getNumericValue() / 1000);
        return Math.floor(epochSecs / windowSecs);
    },
    
    _getRetryAfter: function(windowSecs) {
        var now = new GlideDateTime();
        var epochSecs = Math.floor(now.getNumericValue() / 1000);
        var currentWindow = Math.floor(epochSecs / windowSecs);
        var nextWindowStart = (currentWindow + 1) * windowSecs;
        return nextWindowStart - epochSecs;
    },

    type: 'RateLimitManager'
};

// Scripted REST API Resource Script
(function process(request, response, requestBody, responseBody) {
    
    var rateLimiter = new RateLimitManager();
    
    // Get client identifier (prefer API key, fallback to IP)
    var clientId = request.headers['x-api-key'] || request.getRemoteAddr();
    var endpoint = request.pathInfo;
    
    // Check rate limit (500 requests per hour for this endpoint)
    var rateLimitResult = rateLimiter.isRateLimited(clientId, endpoint, 500, 3600);
    
    if (rateLimitResult.limited) {
        // Set rate limit headers
        response.setStatus(429);
        response.setHeader('Retry-After', rateLimitResult.retryAfter.toString());
        response.setHeader('X-RateLimit-Limit', rateLimitResult.maxRequests.toString());
        response.setHeader('X-RateLimit-Remaining', '0');
        response.setHeader('X-RateLimit-Reset', (new Date(Date.now() + (rateLimitResult.retryAfter * 1000))).toISOString());
        
        responseBody.setBody(JSON.stringify({
            error: 'Rate limit exceeded',
            message: 'Too many requests. Please retry after ' + rateLimitResult.retryAfter + ' seconds.',
            retryAfter: rateLimitResult.retryAfter
        }));
        
        // Log potential abuse
        gs.eventQueue('security.api.rate_limit_exceeded', null, clientId, endpoint);
        return;
    }
    
    // Set rate limit info headers for successful requests
    response.setHeader('X-RateLimit-Limit', rateLimitResult.maxRequests.toString());
    response.setHeader('X-RateLimit-Remaining', rateLimitResult.remaining.toString());
    
    // Continue with normal API logic
    try {
        // Your actual API implementation here
        var result = { message: 'API request processed successfully', timestamp: new GlideDateTime().toString() };
        
        response.setStatus(200);
        responseBody.setBody(JSON.stringify(result));
        
    } catch (ex) {
        gs.error('API Error: ' + ex.message);
        response.setStatus(500);
        responseBody.setBody(JSON.stringify({ error: 'Internal server error' }));
    }
    
})(request, response, requestBody, responseBody);

The RateLimitManager uses GlideCache with time-windowed keys to track request counts per client and endpoint combination. The cache automatically expires entries based on the configured window size, eliminating the need for manual cleanup. The REST API script checks rate limits before processing requests and returns proper HTTP 429 responses with standard rate limiting headers when limits are exceeded.

Alternatives

Database-based rate limiting with custom tables

Provides persistent storage and more complex rate limiting policies but creates database overhead and requires custom cleanup jobs. Use when you need detailed audit trails or complex throttling rules that cache-based solutions cannot support.

ServiceNow Web Service Access Controls

Built-in platform feature with IP-based restrictions and basic authentication controls but lacks granular per-endpoint rate limiting. Suitable for simple scenarios where IP allowlisting and role-based access controls provide sufficient protection.

External API Gateway rate limiting

Provides enterprise-grade rate limiting with advanced policies and analytics but requires additional infrastructure and may not integrate well with ServiceNow's authentication mechanisms. Best for organizations with existing API management platforms.

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