Understanding PUT and PATCH in ServiceNow REST APIs

For ServiceNow developers and administrators working with integration and automation, understanding the nuances of different HTTP methods is crucial. Among these, the PUT and PATCH methods often cause confusion. This article clarifies the distinction between these two methods, specifically within the context of ServiceNow REST APIs, helping you choose the right approach for updating records.

At their core, both PUT and PATCH methods are used to modify existing resources. However, their intended behavior in the broader RESTful world differs significantly. Let's break down each method:

PUT Method

In general RESTful APIs, the PUT method is designed to replace the entire resource at a given URI with the data provided in the request body. This means if any fields of the existing resource are not included in the PUT request, they might be set to their default values or even nullified by the server. Think of it as a complete overwrite of the existing data.

PATCH Method

Conversely, the PATCH method is intended for partial updates to a resource. It only updates the fields that are explicitly included in the request body, leaving the other fields untouched. This is particularly useful when you only need to modify a specific attribute of a record without affecting the rest of its data.

PUT vs. PATCH in ServiceNow Table API

Now, let's address the specific behavior within ServiceNow's Table API, which is commonly used to interact with ServiceNow records via REST. According to the official ServiceNow documentation, for the Table API, both PUT and PATCH methods function identically.

This means that when you use either PUT or PATCH to update a record through the ServiceNow Table API, only the fields you specify in the request body will be modified. Any other fields on the record will remain unchanged.

Practical Examples

Let's say you have a ServiceNow incident record with the following details:

• Number: INC0012345

• Short Description: Network Connectivity Issue

• State: New

• Assigned To: (empty)

If you want to update only the "Assigned To" field, both a PUT request and a PATCH request to the /api/now/table/incident/INC0012345 endpoint with the following JSON payload would achieve the same result in ServiceNow:

JSON

{
  "assigned_to": "John Doe"
}

After either request, the incident record would look like this:

• Number: INC0012345

• Short Description: Network Connectivity Issue

• State: New

• Assigned To: John Doe

Notice that the "Short Description" and "State" fields remain unchanged, even if you used the PUT method, which traditionally might be expected to overwrite the entire resource.

Recommendation

While ServiceNow's Table API treats PUT and PATCH the same, it's generally considered good practice to use the PATCH method for updates. This aligns with the standard RESTful semantics and makes your integrations more consistent with other APIs you might interact with. Using PATCH clearly communicates your intention to perform a partial update, which can improve the readability and maintainability of your code.

Alternative Solutions

While PUT and PATCH are the primary methods for updating records via the Table API, other methods like POST are used for creating new records. Understanding the context of your operation will guide you to the appropriate HTTP method.

Conclusion

In summary, while the general understanding of PUT and PATCH methods differs in the REST world, within the context of ServiceNow's Table API, they currently function identically for updating records. Both methods allow for partial updates, modifying only the fields specified in the request. However, for better adherence to RESTful best practices and improved code clarity, it is recommended to consistently use the PATCH method when performing updates in ServiceNow REST APIs. This ensures your integrations are semantically correct and easier for other developers to understand and maintain. The next step for ServiceNow developers is to adopt the PATCH method for all update operations through the Table API to promote consistency and align with broader industry standards.