REST HTTP Methods
The Now Platform provides various REST APIs, which are active by default. These APIs provide the ability to interact with various ServiceNow functionality within your application. Such functionality includes the ability to perform create, read, update, and delete (CRUD) operations on existing tables (Table API), insert data into, retrieve information from, and run transforms against a MetricBase database (MetricBase Time Series API, and many others.
REST URI format and available parameters
ServiceNow REST APIs follow standard REST API protocol. They also provide “custom” URI and query parameters to ensure backwards compatibility and provide additional functionality such as paginating long lists of results. The following sections describe the functionality behind these custom parameters, which are all optional.
REST API versioning
ServiceNow REST API URIs may include a version number, such as /api/now/v1/table/{tableName}. Version numbers identify the endpoint version that a URI accesses. 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 in the URI, such as /api/now/table/{tableName} , use the latest REST endpoint for your instance version.
Supported HTTP request methods
- GET
- DELETE
- PATCH
- POST
- PUT
What is REST?
REST is an acronym for REpresentational State Transfer and an architectural style for distributed hypermedia systems. Roy Fielding first presented it in 2000 in his famous dissertation. Since then, it has become one of the most widely used approaches for building web-based APIs (Application Programming Interfaces).
REST is not a protocol or a standard, it is an architectural style. During the development phase, API developers can implement REST in a variety of ways.
Like the other architectural styles, REST also has its guiding principles and constraints. These principles must be satisfied if a service interface has to be referred to as RESTful.
REST APIs enable you to develop all kinds of web applications having all possible CRUD (create, retrieve, update, delete) operations.
REST guidelines suggest using a specific HTTP method on a particular type of call made to the server (though technically it is possible to violate this guideline, yet it is highly discouraged).
Use the below-given information to find a suitable HTTP method for the action performed by API.
1. HTTP GET
Use GET requests to retrieve resource representation/information only – and not modify it in any way. As GET requests do not change the resource’s state, these are said to be safe methods.
Additionally, GET APIs should be idempotent. Making multiple identical requests must produce the same result every time until another API (POST or PUT) has changed the state of the resource on the server.
If the Request-URI refers to a data-producing process, it is the produced data that shall be returned as the entity in the response and not the source text of the process, unless that text happens to be the output of the process.
1.1. GET API Response Codes
- For any given HTTP GET API, if the resource is found on the server, then it must return HTTP response code 200 (OK)– along with the response body, which is usually either XML or JSON content (due to their platform-independent nature).
- In case the resource is NOT found on the server then API must return HTTP response code 404 (NOT FOUND).
- Similarly, if it is determined that the GET request itself is not correctly formed then the server will return the HTTP response code 400 (BAD REQUEST).
1.2. Example URIs
2. HTTP POST
Use POST APIs to create new subordinate resources, e.g., a file is subordinate to a directory containing it or a row is subordinate to a database table.
When talking strictly about REST, POST methods are used to create a new resource into the collection of resources.
Responses to this method are not cacheable unless the response includes appropriate Cache-Control or Expires header fields.
Please note that POST is neither safe nor idempotent, and invoking two identical POST requests will result in two different resources containing the same information (except resource ids).
2.1. POST API Response Codes
- Ideally, if a resource has been created on the origin server, the response SHOULD be HTTP response code 201 (Created)and contain an entity that describes the status of the request and refers to the new resource, and a Location
- Many times, the action performed by the POST method might not result in a resource that can be identified by a URI. In this case, either HTTP response code 200 (OK)or 204 (No Content) is the appropriate response status.
2.2. Example URIs
3. HTTP PUT
Use PUT APIs primarily to update an existing resource (if the resource does not exist, then API may decide to create a new resource or not).
If the request passes through a cache and the Request-URI identifies one or more currently cached entities, those entries SHOULD be treated as stale. Responses to PUT method are not cacheable.
3.1. PUT API Response Codes
- If a new resource has been created by the PUT API, the origin server MUST inform the user agent via the HTTP response code 201 (Created)
- If an existing resource is modified, either the 200 (OK)or 204 (No Content) response codes SHOULD be sent to indicate successful completion of the request.
3.2. Example URIs
The difference between the POST and PUT APIs can be observed in request URIs. POST requests are made on resource collections, whereas PUT requests are made on a single resource.
4. HTTP DELETE
As the name applies, DELETE APIs delete the resources (identified by the Request-URI).
DELETE operations are idempotent. If you DELETE a resource, it’s removed from the collection of resources.
Some may argue that it makes the DELETE method non-idempotent. It’s a matter of discussion and personal opinion.
If the request passes through a cache and the Request-URI identifies one or more currently cached entities, those entries SHOULD be treated as stale. Responses to this method are not cacheable.
4.1. DELETE API Response Codes
- A successful response of DELETE requests SHOULD be an HTTP response code 200 (OK)if the response includes an entity describing the status.
- The status should be 202 (Accepted)if the action has been queued.
- The status should be 204 (No Content)if the action has been performed but the response does not include an entity.
- Repeatedly calling DELETE API on that resource will not change the outcome – however, calling DELETE on a resource a second time will return a 404 (NOT FOUND) since it was already removed.
4.2. Example URIs
5. HTTP PATCH
HTTP PATCH requests are to make a partial update on a resource.
If you see PUT requests modify a resource entity too. So to make it more precise – the PATCH method is the correct choice for partially updating an existing resource, and you should only use PUT if you’re replacing a resource in its entirety.
Please note that there are some challenges if you decide to use PATCH APIs in your application:
Support for PATCH in browsers, servers, and web application frameworks is not universal. IE8, PHP, Tomcat, Django, and lots of other software have missing or broken support for it.
Request payload of a PATCH request is not straightforward as it is for a PUT request. e.g.
HTTP GET /users/1
produces below response:
{ “id”: 1, “username”: “admin”, “email”: “email@example.org”}
A sample patch request to update the email will be like this:
HTTP PATCH /users/1[{ “op”: “replace”, “path”: “/email”, “value”: “new.email@example.org” }]
There may be the following possible operations are per the HTTP specification.
[ { “op”: “test”, “path”: “/a/b/c”, “value”: “foo” },{ “op”: “remove”, “path”: “/a/b/c” },
{ “op”: “add”, “path”: “/a/b/c”, “value”: [ “foo”, “bar” ] },
{ “op”: “replace”, “path”: “/a/b/c”, “value”: 42 },
{ “op”: “move”, “from”: “/a/b/c”, “path”: “/a/b/d” },
{ “op”: “copy”, “from”: “/a/b/d”, “path”: “/a/b/e” } ]
The PATCH method is not a replacement for the POST or PUT methods. It applies a delta (diff) rather than replacing the entire resource.
6. Summary of HTTP Methods
The below table summarises the use of HTTP methods discussed above.
| HTTP Method | CRUD | Collection Resource (e.g. /users) | Single Resouce (e.g. /users/123) |
|---|---|---|---|
| POST | 5 | 201 (Created), ‘Location’ header with link to /users/{id} containing new ID | Avoid using POST on a single resource |
| GET | Create | 200 (OK), list of users. Use pagination, sorting, and filtering to navigate big lists | 200 (OK), single user. 404 (Not Found), if ID not found or invalid |
| READ | Update/Replace | 405 (Method not allowed), unless you want to update every resource in the entire collection of resource | 200 (OK) or 204 (No Content). Use 404 (Not Found), if ID is not found or invalid |
| PATCH | Partial Update/Modify | 405 (Method not allowed), unless you want to modify the collection itself | 200 (OK) or 204 (No Content). Use 404 (Not Found), if ID is not found or invalid |
| DELETE | Delete | 405 (Method not allowed), unless you want to delete the whole collection — use with caution | 200 (OK). 404 (Not Found), if ID not found or invalid |
7. Glossary
7.1. Safe Methods
Request methods are considered safe if their defined semantics are essentially read-only. The client does not request, and does not expect, any state change on the origin server as a result of applying a safe method to a target resource.
The GET, HEAD, OPTIONS, and TRACE methods are considered safe methods. As per HTTP specification, the GET and HEAD methods should be used only for retrieval of resource representations – and they do not update/delete the resource on the server.
The purpose of distinguishing between safe and unsafe methods is to allow automated retrieval processes (spiders) and cache performance optimization (pre-fetching) to work without fear of causing harm.
Safe methods allow user agents to represent other methods, such as POST, PUT and DELETE, in a unique way so that the user is made aware of the fact that a possibly unsafe action is being requested – and they can update/delete the resource on the server and so should be used carefully.
7.2. Idempotent Methods
The term idempotent is used more comprehensively to describe an operation that will produce the same results if executed once or multiple times.
In HTTP specification, the PUT, DELETE and safe methods (GET, HEAD, OPTIONS, TRACE) are idempotent methods.
Idempotence is a handy property in many situations, as it means that an operation can be repeated or retried as often as necessary without causing unintended effects.
With non-idempotent operations, the algorithm may have to keep track of whether the operation was already performed or not.
Like the definition of safe methods, the idempotent property only applies to what has been requested by the user; a server is free to log each request separately or retain a revision control history.
By: Puneet