REST API

From ServiceNow Wiki
Home > Integrate > Web Services > REST API
Jump to: navigation, search

This article applies to Fuji. For more current information, see REST API at https://developer.servicenow.com

The ServiceNow Wiki is no longer being updated. Please refer to https://developer.servicenow.com/app.do#!/home for the latest information.

Web Services

1 Overview

REST (REpresentational State Transfer) is a simple stateless architecture that generally runs over HTTPS/TLS. The REST style emphasizes that interactions between clients and services are enhanced by having a limited number of operations. Flexibility is provided by assigning resources their own unique universal resource indicators (URIs). Because each operation (GET, POST, PUT, and DELETE) has a specific meaning, REST avoids ambiguity.

The REST API is active by default in all instances, starting with the Eureka release.

RESTful web services offer several advantages, including:

  • Support for different HTTP methods to perform different actions
  • Detailed response codes and header information
  • Pagination support for large data sets
  • Streaming data on GET requests


For more information, see Getting Started with REST.

2 ServiceNow REST API Resources

To view the the REST API resources available in your instance, along with the correct formats for the supported methods, use the REST API Explorer. To access the explorer, navigate to System Web Services > REST API Explorer. (Prior to the Fuji release, navigate to System Web Services > APIs to view available REST APIs.)

2.1 Available APIs

The following REST APIs are available:

2.2 Supported Methods

The following methods conform to the REST standard and are available in ServiceNow:

  • GET
  • POST
  • PUT
  • PATCH
  • DELETE

Each API may support certain methods. Refer to the documentation for each API to view detailed method information.

3 Roles

Role name Description
rest_service Can use the REST API to perform REST web service operations such as querying or inserting records.
web_service_admin Can access the System Web Services application menu and the REST modules.

4 API Version

REST API URIs may specify a version number, such as /api/now/v1/table/(tablename) or no version number, such as /api/now/table/(tableName). URIs with a version number provide a consistent interface that is guaranteed to maintain backwards compatibility in future ServiceNow releases. For example, if the default response format for a particular HTTP method changes in a release, versioned URIs continue to use the previous format.

By specifying a version number in your URIs, you can ensure that future updates to the REST API do not negatively impact your integration. URIs that do not specify a version number use the most recent REST API behavior available with your instance version, which may change when you upgrade.

5 Headers

Each of the supported methods can be overridden if you set the X-http-method-override header. The Accept and Content-Type request headers are required for proper data formatting. These request headers have the following valid values:

  • Accept: application/json, application/xml
  • Content-Type: application/json, application/xml

POST, PUT, and PATCH operations require you to provide both headers. The GET and DELETE operations require only the Accept header. Failing to provide the required headers results in a 400 Bad Request error.

6 Security

By default, you must include user credentials in a REST request. The REST API supports basic authentication and OAuth for enforcing access controls to web resources. The user record that is used for authentication is subject to access control in the same way as an interactive user. Each request requires the proper authentication information. There is no support for mutual authentication for inbound REST requests.

REST supports cookies for binding to the existing session.

6.1 Table Access

All tables, including base system tables, global tables, and scoped tables are accessible via web services by default. You must fulfill any other web service security requirements, such as basic authentication and ACLs to access tables via web services.

You can control direct web service access to tables using the Allow access to this table via web services check box on the table Application Access settings. This check box must be selected to allow web service interaction with the table.

Note
Note: The application access fields controlling CRUD operations, such as Can read or Can create do not apply to web service requests.


6.2 OAuth with REST

Using OAuth, you can pass a user ID and password once, and then use a token for subsequent REST requests instead of submitting credentials with each request. In this way, OAuth can improve system security by reducing the number of times you submit user credentials. You can use OAuth to authenticate REST requests starting with the Fuji release. You must enable the OAuth plugin to use this functionality.

  1. Enable OAuth in the ServiceNow instance that the external client will connect to.
    You may need to activate the OAuth plugin and set the OAuth property if OAuth is not yet enabled on the instance.
  2. Register a client application and create an endpoint.
  3. Record the client_id and client_secret values from the previous step to use when requesting an access token.
  4. To get an access token, use your REST client, such as cURL or Postman, to send a request to the OAuth endpoint (oauth_token.do).
    Format the request as a URL-encoded HTTP POST body and include the required parameters.
  5. Record the access token and refresh token from the response.
  6. Submit the access token with subsequent REST requests.

7 REST Response HTTP Status Codes

Status Code Message Details
200 Success Success with response body.
201 Created Success with response body.
204 Success Success with no response body.
400 Bad Request The request URI does not match the APIs in the system, or the operation failed for unknown reasons. Invalid headers can also cause this error.
401 Unauthorized The user is not authorized to use the API.
403 Forbidden The requested operation is not permitted for the user. This error can also be caused by ACL failures, or business rule or data policy constraints.
404 Not found The requested resource was not found. This can be caused by an ACL constraint or if the resource does not exist.
405 Method not allowed The HTTP action is not allowed for the requested REST API, or it is not supported by any API.

8 Dot-Walking in REST Requests

You can use dot-walking when specifying the sysparm_query or sysparm_fields parameters in requests to REST APIs that support those parameters.

Note
Note: The Import Set API does not support dot-walking.


You can filter queries using related record values by dot-walking in the sysparm_query parameter. For example, you can retrieve all incident records where the incident Company has a specific Stock symbol value.

https://<instance>.service-now.com/api/now/table/incident?sysparm_query=company.stock_symbol=NYX 


You can view field values from multiple tables by dot-walking in the sysparm_fields parameter. For example, you can retrieve the Name, Sys_id, and Department of each user that has certain roles, as well as the role Name.

The request runs on the User Roles [sys_user_has_role] table which defines a many-to-many relationship between users and roles. The response includes field values from the User [sys_user] and Roles [sys_user_role] tables.

https://<instance>.service-now.com/api/now/table/sys_user_has_role?
sysparm_fields=role%2Crole.name%2Cuser%2Cuser.name%2Cuser.sys_id%2Cuser.department&
sysparm_query=role%3D3d43716d0f6002003a2d47bce1050e0d%5EORrole%3Dac73b52d0f6002003a2d47bce1050eec&sysparm_display_value=true

9 Debugging REST Queries

When the glide.rest.debug system property is set to true, it logs all REST processing, including processing durations, headers, and the request body. Prolonged use of this property can affect performance, so it is best to use it while debugging REST processing, and then set the property back to false.

9.1 Sample Log Output

2014-03-19 11:10:37 (633) http-12 New transaction 083A6031D7231100261253B2B252035C #28 /api/now/table/incident
2014-03-19 11:10:37 (653) REST API-thread-1 SYSTEM DEBUG: [REST API] RESTAPIProcessor : Started initializing REST Request 
2014-03-19 11:10:37 (653) REST API-thread-1 SYSTEM DEBUG: [REST API] RESTAPIProcessor : Request Method:POST 
2014-03-19 11:10:37 (656) REST API-thread-1 SYSTEM DEBUG: [REST API] RESTAPIProcessor : Request Header: host:localhost:8080
2014-03-19 11:10:37 (656) REST API-thread-1 SYSTEM DEBUG: [REST API] RESTAPIProcessor : Request Header: user-agent:Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:12.0) Gecko/20100101 Firefox/12.0
2014-03-19 11:10:37 (656) REST API-thread-1 SYSTEM DEBUG: [REST API] RESTAPIProcessor : Request Header: accept:application/json
2014-03-19 11:10:37 (656) REST API-thread-1 SYSTEM DEBUG: [REST API] RESTAPIProcessor : Request Header: accept-encoding:gzip, deflate
2014-03-19 11:10:37 (656) REST API-thread-1 SYSTEM DEBUG: [REST API] RESTAPIProcessor : Request Header: connection:keep-alive
2014-03-19 11:10:37 (657) REST API-thread-1 SYSTEM DEBUG: [REST API] RESTAPIProcessor : Request Header: content-type:application/json; charset=UTF-8
2014-03-19 11:10:37 (657) REST API-thread-1 SYSTEM DEBUG: [REST API] RESTAPIProcessor : Request Header: content-length:31
2014-03-19 11:10:37 (657) REST API-thread-1 SYSTEM DEBUG: [REST API] RESTAPIProcessor : Request Header: cookie:glide_user_route=glide.20e7f4cd6bdc0d444810117aacc0eeae; JSESSIONID=F07CE6ACF8AF237CB239AF43B7F360BF; glide_user="U0N2Mjo0MDNhNjAzMWQ3MjMxMTAwMjYxMjUzYjJiMjUyMDM2OTo2ODE2Zjc5Y2MwYTgwMTY0MDFjNWEzM2JlMDRiZTQ0MQ=="; glide_user_session="U0N2Mjo0MDNhNjAzMWQ3MjMxMTAwMjYxMjUzYjJiMjUyMDM2OTo2ODE2Zjc5Y2MwYTgwMTY0MDFjNWEzM2JlMDRiZTQ0MQ=="
2014-03-19 11:10:37 (657) REST API-thread-1 SYSTEM DEBUG: [REST API] RESTAPIProcessor : Request Header: pragma:no-cache
2014-03-19 11:10:37 (657) REST API-thread-1 SYSTEM DEBUG: [REST API] RESTAPIProcessor : Request Header: cache-control:no-cache
2014-03-19 11:10:38 (357) REST API-thread-1 SYSTEM [REST API] RouteRegistry : Loaded Routes to Cache
2014-03-19 11:10:38 (357) REST API-thread-1 SYSTEM DEBUG: [REST API] RouteRegistry : Route loading time 0:00:00.105
2014-03-19 11:10:38 (357) REST API-thread-1 SYSTEM DEBUG: [REST API] URIHandler : Resolving URI: /now/table/incident
2014-03-19 11:10:38 (391) REST API-thread-1 SYSTEM DEBUG: [REST API] RESTAPIProcessor : URI Resolving Duration 387570:10:38.391
2014-03-19 11:10:38 (424) REST API-thread-1 SYSTEM DEBUG: [REST API] RESTAPIProcessor : Finished initializing REST Request
2014-03-19 11:10:38 (540) REST API-thread-1 083A6031D7231100261253B2B252035C #28 /api/now/table/incident Parameters -------------------------
api=api
2014-03-19 11:10:38 (541) REST API-thread-1 083A6031D7231100261253B2B252035C DEBUG: [REST API] RESTAPIProcessor : Processing REST Request /api/now/table/incident
2014-03-19 11:10:38 (541) REST API-thread-1 083A6031D7231100261253B2B252035C DEBUG: [REST API] RESTAPIProcessor : Pre-Service processing duration 0:00:00.000
2014-03-19 11:10:38 (548) REST API-thread-1 083A6031D7231100261253B2B252035C DEBUG: [REST API] ServiceHandler : Invoking Service TableAPIService
2014-03-19 11:10:38 (552) REST API-thread-1 083A6031D7231100261253B2B252035C DEBUG: [REST API] TableAPIService : Inserting record
2014-03-19 11:10:38 (560) REST API-thread-1 083A6031D7231100261253B2B252035C DEBUG: [REST API] RequestDeserializer : Incoming Request Body:{"short_description":"test me"}
2014-03-19 11:10:39 (508) REST API-thread-1 083A6031D7231100261253B2B252035C DEBUG: [REST API] TableAPIService : Glide Record Insert Duration 0:00:00.956
2014-03-19 11:10:39 (508) REST API-thread-1 083A6031D7231100261253B2B252035C DEBUG: [REST API] TableAPIService : Querying for inserted record
2014-03-19 11:10:39 (513) REST API-thread-1 083A6031D7231100261253B2B252035C #### Compiler Stats ####
2014-03-19 11:10:39 (514) REST API-thread-1 083A6031D7231100261253B2B252035C Compiles: 600, time: 1,130ms
2014-03-19 11:10:39 (514) REST API-thread-1 083A6031D7231100261253B2B252035C Cache name: "syscache_expression", max: 8,192, size: 599, seeks: 34,182, hits: 32,980, misses: 1,202, flushed: 0
2014-03-19 11:10:39 (514) REST API-thread-1 083A6031D7231100261253B2B252035C Total classes: 1,402, bytecode length: 3,263,462
2014-03-19 11:10:39 (514) REST API-thread-1 083A6031D7231100261253B2B252035C Total loaders created: 601, unloaded: 0, existing: 601
2014-03-19 11:10:39 (652) REST API-thread-1 083A6031D7231100261253B2B252035C DEBUG: [REST API] TableAPIService : Creating service result for insert request
2014-03-19 11:10:39 (655) REST API-thread-1 083A6031D7231100261253B2B252035C DEBUG: [REST API] ServiceHandler : End of Service InvocationTableAPIService
2014-03-19 11:10:39 (655) REST API-thread-1 083A6031D7231100261253B2B252035C DEBUG: [REST API] ServiceHandler : Service Invocation Duration 0:00:01.107
2014-03-19 11:10:39 (660) REST API-thread-1 083A6031D7231100261253B2B252035C DEBUG: [REST API] ServiceHandler : Serializing Response
2014-03-19 11:10:39 (706) REST API-thread-1 083A6031D7231100261253B2B252035C DEBUG: [REST API] ServiceHandler : End of Response Serialization
2014-03-19 11:10:39 (706) REST API-thread-1 083A6031D7231100261253B2B252035C DEBUG: [REST API] ServiceHandler : Response Serialization Duration 0:00:00.046
2014-03-19 11:10:39 (706) REST API-thread-1 083A6031D7231100261253B2B252035C DEBUG: [REST API] RESTAPIProcessor : Service handling duration 0:00:01.165
2014-03-19 11:10:39 (706) REST API-thread-1 083A6031D7231100261253B2B252035C DEBUG: [REST API] RESTAPIProcessor : End of Request Processing
2014-03-19 11:10:39 (706) REST API-thread-1 083A6031D7231100261253B2B252035C DEBUG: [REST API] RESTAPIProcessor : REST Request Processing time 0:00:01.165
2014-03-19 11:10:39 (707) REST API-thread-1 083A6031D7231100261253B2B252035C #28 /api/now/table/incident -- total transaction time: 0:00:02.074, total wait time: 0:00:00.001, session wait: 0:00:00.000, semaphore wait: 0:00:00.001, source: 127.0.0.1

10 Troubleshooting

For troubleshooting information, see knowledge base article KB0535048.

11 Enhancements

11.1 Fuji

Was this article helpful?
Yes, I found what I needed
No, I need more assistance