Scripted REST API example - script samples
Summarize
Summary of Scripted REST API example - script samples
This guide provides practical script examples for creating and handling Scripted REST API resources in ServiceNow. It demonstrates how to process different types of requests, extract parameters, handle errors, and format responses. The examples help customers build robust REST APIs by showing common use cases with clear, reusable code snippets.
Show less
Key Features
- Query Parameters Handling: Retrieve query parameters and custom headers from GET requests.
- Path Parameters Handling: Extract path parameters from the request URL in GET requests.
- Using Script Includes: Illustrates using script includes to encapsulate reusable logic for cleaner REST API scripts.
- Parsing POST Requests: Examples show handling both string and binary data in POST request bodies and returning relevant responses.
- Error Handling: Demonstrates how to send standardized HTTP error responses such as Not Acceptable, Bad Request, Conflict, Not Found, Unsupported Media Type, and custom service errors, improving API robustness and client communication.
- Complex Request Body Parsing: Shows how to parse JSON or XML arrays in POST requests and extract multiple data values in the resource scripts.
- Content Negotiation: Supports both JSON and XML request formats, with response formatting controlled by the Accept header to consistently return JSON responses.
What to Expect
By using these script examples, ServiceNow customers can efficiently build Scripted REST APIs that:
- Handle various request types and data formats.
- Extract and utilize query, path, and body parameters effectively.
- Implement clean and maintainable code through script includes.
- Return appropriate HTTP error codes with descriptive messages.
- Support flexible request and response content types, enabling integration with diverse clients.
These examples serve as a foundation for developing customized REST APIs tailored to your enterprise workflows and integration needs.
These examples demonstrate how to create various resource scripts for a scripted REST API.
Query parameters GET example
This example demonstrates how to get query parameter values from a request.
/**
* GET - Sample Request API - Query Params
*/
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
var uri = request.uri;
var url = request.url;
var queryParams = request.queryParams;
var customHeader = request.getHeader('X-Custom');
return {
"uri": uri,
"url": url,
"queryParams": queryParams,
"customHeader": customHeader
};
})(request, response);Path parameters GET example
This example demonstrates how to get path parameter values from a request.
/**
* GET - Sample Request API - Path Params
*/
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
var uri = request.uri;
var url = request.url;
var path = request.pathParams;
return {
"uri": uri,
"url": url,
"path_params": path,
"path.id": path.id
};
})(request, response);
Script include GET example
This example demonstrates how to use a script include to provide a response. By using a script include you can reuse common code and maintain readability in the REST service scripts.
/**
* GET - Sample Request API - Script Include
*/
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
var responseObj = global.SampleDataUtil.getSampleJSON();
return responseObj;
})(request, response);String POST example
This example demonstrates how to parse a POST message with a string body and send a response based on the request.
/**
* POST - Sample Request API - dataString
* sample usage:
* var requestBody = request.body;
* var requestString = requestBody.dataString;
*/
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
var requestBody = request.body;
var requestString = requestBody.dataString;
return {"requestString": requestString};
})(request, response);Binary POST example
This example demonstrates how to parse a POST message with a binary body and send a response based on the request.
/**
* POST - Sample Request API - Body
*/
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
var body = request.body.data;
//do any additional processing on the request body, such as inserting a new record.
return {
"body.id": body.id
};
})(request, response);Not acceptable error example
This example demonstrates how to respond with a not acceptable error. Use this error type when the request Accept header value is not supported by the web service.
/**
* Sample Not Acceptable Error Sample
*/
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
response.setError(new sn_ws_err.NotAcceptableError('sample error message'));
})(request, response);Bad request error example
This example demonstrates how to respond with a bad request error. Use this error type to indicate a mistake in the request syntax.
/**
* Bad Request Error Sample
*/
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
response.setError(new sn_ws_err.BadRequestError('sample error message'));
})(request, response);Conflict error example
This example demonstrates how to respond with a conflict error. Use this error type in the event of multiple conflicting requests, such as multiple updates to the same record.
/**
* Error Response: Conflict Error Sample
*/
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
response.setError(new sn_ws_err.ConflictError('sample error message'));
})(request, response);Not found error example
This example demonstrates how to respond with a not found error. Use this error type if the requested resource does not exist or is unavailable.
/**
* Error Response: Not Found Error Sample
*/
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
response.setError(new sn_ws_err.NotFoundError('sample error message'));
})(request, response);Unsupported media type error example
This example demonstrates how to respond with an unsupported media type error. Use this error type to indicate that the Content-Type of the request is unsupported.
/**
* Error Response: Unsupported Media Type Error Sample
*/
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
response.setError(new sn_ws_err.UnsupportedMediaTypeError('sample error message'));
})(request, response);Service error example
This example demonstrates how to respond with a generic service error. The ServiceError object allows you to define the status code, message, and error detail. Use a ServiceError if the predefined error types do not meet your needs.
/**
* Error Response: Custom Error Sample
*/
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
var myError = new sn_ws_err.ServiceError();
myError.setStatus(418);
myError.setMessage("I am a Teapot");
myError.setDetail("Here are the details about this error");
response.setError(myError);
})(request, response);
Scripted REST resource script example
/**
* POST - Sample Request API - Body
*/
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
var body = request.body.data,
id0,name0,id1,name1;
name0 = body[0].name; // 'user0'
id0 = body[0].id; // '1234'
name1 = body[1].name; // 'user1'
id1 = body[1].id; // '5678'
return {
"id": id0,
"name": name0,
"id1": id1,
"name1": name1
};
})(request, response);Requests
| JSON Request | XML Request |
|---|---|
|
|
Responses
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Tue, 04 Aug 2015 15:20:44 GMT
Server: ServiceNow
Connection: close
Set-Cookie: BIGipServerpool_<Instance>=880838154.47166.0000; path=/
{"result":{"id":1234,"id1":5678,"name":"user0","name1":"user1"}}