REST Flashcards
Basic image of how a REST call works
In an inbound request, a third-party application requests an action through a ServiceNow API. Example ServiceNow APIs include:
- Table API:
- Attachment API:
- Email API:
- Table API: Create, read, update, and delete records from a table
- Attachment API: Upload and query file attachments
- Email API: Send and receive email messages using REST
The fields in the Prepare request section of the REST API Explorer form are determined by which Namespace, API Name, API Version, and REST method is selected.
- Namespace: Select the web service scope
- global: Globally scoped APIs
- now: REST APIs provided by ServiceNow
- private_scope_name: Namespace format used for APIs (scripted web services) in privately-scoped applications
- API Name: Select an API to configure and test in the REST API Explorer
- API Version: Select a specific API version or choose latest
- Method: Select from the list of available REST methods based on the Namespace, API Name, and API Version. The arrowhead indicates the selected method.
Request Parameters consist of:
- _
- _
- _
Request Parameters consist of:
- Path parameters
- Query parameters
- Request headers
The list of path parameters depends on the endpoint URL. Path parameters are enclosed in curly braces in the endpoint URL. The values set in the path parameter field are substituted into the endpoint URL when a request is sent.
Request parameters are added to the endpoint URL by the REST API Explorer when the request is sent. The query parameters are specific to the selected API method.
What are the Query Parameters:
A default set of query parameters are displayed for the API. To add additional query parameters, use the Add query parameter button to add a new parameter to the query. For a complete list and detailed description of an API’s query parameters, select the API documentation menu item from the REST API Explorer menu.
Request headers define the format of the Request and Response.
Use the Add header button to add additional headers to the request. For the ServiceNow APIs, two useful additional header parameters are:
X-WantSessionNotificationMessages: Set to true to return notifications that have not already been consumed for the existing session.
X-WantSessionDebugMessages: Enable Session Debug and set the header value to true to return session debug logs.
The REST API Explorer responds as if the request came from a third party application:
Request
Response
Response Body
The ServiceNow API Response consists of:
- _
- _
- _
- HTTP status code
- Response headers
- Response body
What are the standard HTTP status codes that are used?
- _
- _
- _
- _
- _
HTTP Status Code
ServiceNow APIs return standard HTTP status codes. Generally speaking:
- 1xx: Informational
- 2xx: Success
- 3xx: Redirection
- 4xx: Client Error
- 5xx: Server Error
The response codes indicate the success or failure of the transaction.
The HTTP status codes refer to the interaction with the REST service provider. The status codes do not tell anything about the requested data. The REST transaction request can complete successfully even if no data is returned.
Response Headers
The Headers section shows the returned headers and ___ ___.
what is the Response Body
The response body is the data object returned by the ServiceNow web service provider. The response body varies depending on the selected API. In the example, the Aggregate API returns the count of open incident records in the past year with a priority of Critical or High. The results are grouped by the user in the Assigned to field.
Why would a user have the “Web service access only” checbox selected on their user profile?
Create an API Request User
Users with the Web service access only option set on their user record cannot log into the ServiceNow UI. This option allows the user credentials to be used only to authorize API connections. To set this option, open the user record for editing using the User Administration > Users module.
What should be done to protect tables from REST requests?
Administrators can disable web service access to tables. On the table record, open the Application Access section and de-select the Allow access to this table via web services option. REST requests are not accepted for tables unless this option is selected (checked). To set this option, open the table record for editing using the System Definition > Tables module.
IMPORTANT: The REST API Explorer ignores this setting. The REST API Explorer can interact with tables with the Allow access to this table via web services option disabled.
What are CORS Rules
Cross-Origin Resource Sharing (CORS) rules control which domains can access specific REST API endpoints. To create a CORS rule, use the All menu to open System Web Services > REST > CORS Rules.
In the example, the resource https://www.test-cors.org can only access the Table API using the GET method.
- REST API:
- Domain:
- Max age:
- HTTP Methods:
- HTTP Headers:
- REST API: The REST API the CORS rule applies to.
- Domain: The domain for the CORS rule. Specify the domain using an IP Address or a domain pattern.
- Max age: The number of seconds to cache the client session. After an initial CORS request, further requests from the same client within the specified time do not require a preflight message. If a value is not specified, the default value of 0 indicates that all requests require a preflight message.
- HTTP Methods: The methods allowed.
- HTTP Headers: A comma-separated list of HTTP headers to send in the response. Specified headers are added to the Access-Control-Expose-Headers header.
There are a number of requirements for specifying the domain including:
- _
- _
- _
There are a number of requirements for specifying the domain including:
- Start with http:// or https://
- Must be an IP address or domain pattern
- Can contain only one wildcard *
The REST API Explorer creates code samples for integrating with the ServiceNow APIs in several commonly used languages:
The REST API Explorer creates code samples for integrating with the ServiceNow APIs in several commonly used languages:
ServiceNow Script
cURL
Python
Ruby
JavaScript
Perl
Powershell
QUESTION: True or False? In an inbound REST integration, ServiceNow is the web service provider.
true
QUESTION: Which of the following is the application in ServiceNow used to construct and test API requests to a ServiceNow instance?
1. REST API Provider
2. REST API Explorer
3. REST Message Explorer
4. REST Request Builder
5. REST Request Explorer
ANSWER: The correct response is 2. REST API Explorer.
QUESTION: Which one of the following is NOT selected to determine what fields are available in the Prepare request section of the REST API Explorer?
1. Path parameters
2. Method
3. API Name
4. Namespace
5. API Version
ANSWER: The correct response is 1. Path parameters. Select the Namespace, API Name, API Version, and Method to determine which fields are available in the Prepare request section.
QUESTION: The highlighted items are examples of which type of values?
The image shows a URL from the Table API with a PUT method that accesses /api/now/table/{tableName}/{sys_id} with {tableName}/{sys_id} highlighted.
* Request parameters
* Request headers
* Query parameters
* Path parameters
* Response headers
ANSWER: The correct response is 4. Path parameters.
Scripted REST header example:
- Header name: HTTP header field name.
- API definition: API the header is part of.
- Short description: Description of what information should be passed in the header.
- Example value: Sample of the data to be passed to demonstrate how to use the header.
Example query parameters
- Query parameter name: Name of the parameter. By convention, query parameters are lowercase and use underscores in place of spaces. Many query parameters in baseline ServiceNow Scripted REST APIs start with the string sysparm_.
- API definition: API the query is part of.
- Short description: Description of what information should be passed in the query.
- Example value: A sample of the data to be passed to demonstrate how to use the query.
What is the purpose of the pathParams object
The pathParams object allows script access to path parameters passed in the request URL. The available path parameters are determined by the Scripted REST Service resources.
The userinfo resource URL from the Demo Service is:
https://<instance>/api/<namespace>/demo_service/userinfo/{user_id}</namespace></instance>
The path parameters are passed in when the service is invoked.
//get pathParams object
var pathparams = request.pathParams;
//get user_id property value from pathparams object
var userID = pathparams.user_id;
What is the purpose of the queryParams object
The queryParams object allows script access to the query parameters from the web service request.
https://<instance_rest_endpoint>/?demo_query=active%3Dtrue
The demo_query parameter value is passed in when the service is invoked.</instance_rest_endpoint>
//get queryParams object
var queryparams = request.queryParams;
//value of myQueryParam is active=true
var myQueryParam = queryparams.demo_query;
The value of the myQueryParam variable after the example script executes is active=true.
What is the purpose of the headers object
The headers object contains all headers property value pairs from the request
//get the headers from the request
var headers = request.headers;
//get the value of the Accept property
var acceptHeader = headers.accept;
The properties of the request.headers object can be different for different APIs. The request.headers properties for the Demo Service API include accept, from, and content-type. Notice that all request.headers property names are lowercase even if defined in the API using uppercase characters. The script used to log the request.headers property also logged the data type. Notice that all properties are strings.
what is the purpose of the getSupportedResponseContentTypes() method
The getSupportedResponseContentTypes() method returns an array of string values where each string is a content type, such as application/json.
var contentTypes = [];
contentTypes = request.getSupportedResponseContentTypes();
for(i=0;i<contentTypes.length;i++){
gs.info("content type [" + i + "] = " + contentTypes[i]); } The contentTypes array has one element for the Demo Service.
What will this return:
(function process(/RESTAPIRequest/ request, /RESTAPIResponse/ response) {
// implement resource here
// Get value from the user_id path parameter passed in the URL
var requestUser = request.pathParams.user_id;
// Get value of the demo_query query parameter passed in the URL
var requestDemoQuery = request.queryParams.demo_query;
// Query the sys_user table to get the user record for the user passed in
// the user_id path parameter
var requestUserName = new GlideRecord(‘sys_user’);
requestUserName.get(requestUser);
// Aggregation 1: Incident table
// Get the count of Incident table records where the user from the user_id path
// parameter is the Caller.
var userIncidentCount = new GlideAggregate(‘incident’);
userIncidentCount.addAggregate(‘COUNT’);
userIncidentCount.addQuery(‘caller_id’,requestUser);
userIncidentCount.addEncodedQuery(requestDemoQuery);
userIncidentCount.query();
var incidents = 0;
if (userIncidentCount.next()) {
incidents = userIncidentCount.getAggregate(‘COUNT’);
}
// Aggregation 2: Change request table
// Get the count of Change request table records where the user from the user_id path
// parameter is the Requested by.
var userChangeCount = new GlideAggregate(‘change_request’);
userChangeCount.addAggregate(‘COUNT’);
userChangeCount.addQuery(‘requested_by’,requestUser);
userChangeCount.addEncodedQuery(requestDemoQuery);
userChangeCount.query();
var changes = 0;
if (userChangeCount.next()) {
changes = userChangeCount.getAggregate(‘COUNT’);
}
// Aggregation 3: Problem table
// Get the count of Problem table records where the user from the user_id path
// parameter is the Opened by.
var userProblemCount = new GlideAggregate(‘problem’);
userProblemCount.addAggregate(‘COUNT’);
userProblemCount.addQuery(‘opened_by’,requestUser);
userProblemCount.addEncodedQuery(requestDemoQuery);
userProblemCount.query();
var problems = 0;
if (userProblemCount.next()) {
problems = userProblemCount.getAggregate(‘COUNT’);
}
//Create a body object. Add property value pairs to the body.
var body = {};
body.numInc = incidents;
body.numChg = changes;
body.numPrb = problems;
body.user = {“User name”: requestUserName.user_name,
“User ID”: requestUser};
// Send the response object, which is returned to the requestor, to the body object.
response.setBody(body);
})(request, response);
In the Request section, notice the format of the request. Can you locate the path parameter and the query parameter?
