There’s a joy to using RESTful APIs to programmatically talk with different systems to build something useful, such as my Grafana dashboard. As I dive deeper into my new gig, I’ve been attempting to learn more about communicating with RESTful services using different methods. This includes methods I’ve not used before and concatenating multiple calls into one. One of the methods that I’ve recently stumbled upon is PATCH. It was listed as an available method by the Rubrik API, so I decided to peel the onion back a few layers.

Read the Docs has a clever little blurb on PUT vs PATCH. Both methods are shown to “update a resource” in the semantics chart. The difference? PUT updates the entire resource while PATCH updates only the resources fields provided in the call. With PUT, I need to provide data for every field that the resource contains, otherwise the missing fields are set to null or the request fails. These are annoyances I’ve hit with the VMware NSX API on a number of occasions when wanting to update specific fields contained within an NSX Edge resource. The PATCH method sounds useful for updating one of a resource’s fields, such as the password field, without having to first GET all of the other fields.

Safe Methods

The RESTful Cookbook has a nifty example on when to use PATCH. At the bottom, there’s a single line that caught my eye:

PATCH is neither safe nor idempotent.

That sounds terrifying. What the heck does that even mean? The term “Safe” refers to IETF RFC 7231 section 4.2.1 entitled Safe Methods. In a nutshell, methods that modify data are not classified as safe. You should be cautious when using these, and validate that success or failure of the call, before moving on. This little snipet is the meat behind the term:

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.

Fair enough. GET, HEAD, OPTIONS, and TRACE are considered safe. Assuming the designer of the API did his or her job correctly, you don’t have to worry about invoking these methods and altering data.

Idempotent Methods

Idempotent, which is a funky word, is used to describe a method that can be invoked more than once with the same results. Using a GET method on a resource will return the same results every time (unless someone else has updated the resource). The online definitions are a bit dry and ugly, but the REST API Tutorial site has an educational (and funny) video that adds clarity. The PATCH method is not listed as being idempotent. I found this confusing at first – if I update a field within a resource multiple times, wouldn’t that field simply return the same value each time? Fortunately, Stack Exchange has a logical answer to the question:

Whether PATCH can be idempotent or not depends strongly on how the required changes are communicated. For example, if the patch format is in the form of {change: ‘Name’ from: ‘benjamin franklin’ to: ‘john doe’}, then any PATCH request after the first one would have a different effect (a failure response) than the first request.

That makes sense. From my limited experience thus far, most all of my PATCH requests are idempotent, but the method itself doesn’t require it.

There you have it. PATCH, the non-safe and non-idempotent method is totally rad. I hope to see it more out in the wild, unless I start to see comments with horror stories stating otherwise. 🙂