RESTful web services: When to use HTTP PATCH method

HTTP is a very interesting method but just a few application, SOA or Enterprise Integration developers use all of its capabitities. POST and GET among all HTTP Methods are the most used Method followed by PUT. Yet not very used the PATCH method is very useful and it plays a so specific role that it worth understanding its semantics.

In order to better understand HTTP’s PATCH method let’s have a real-world inspired example. The following figure is a simplified version of a integration project that I’ve been working on.

Users  connect to the cloud-based Payroll System in order to do many activivies such as employee data management.  This system holds the “master data” for employees.

Now imagine everytime an employee data is created or edited in the Payroll System we have to send this new/edited data  (the “1” in the figure) to other systems such as a Sales/Remuneration system (the “2” in the figure), a Performance Appraisal System (the “3” in the figure) and so on (the “4” in the figure).

As described in one of my last posts When to use HTTP Post and HTTP PUT, both POST and PUT create or edit a full Resource Representation, i.e., when you have all of its data.

Bringing it to our Payroll example it means we would create a RESTful web service – in our Tibco ESB – based on POST/PUT  method if the Payroll would send not only the edited Employee data but all its data (all attributes). But that was not the case of the Payroll system I was integrating with. The Payroll sends only the edited data, I mean, if a employee move to another apartment in the same building the payroll would send just the Address’ complement without the street name, city, postal code and so on so forth. That’s why HTTP PATCH was created for!

While in a PUT/POST request, the enclosed entity is considered to be a modified version of the resource stored on the
origin server, and the client is requesting that the stored version be replaced. With PATCH, however, the enclosed entity contains a set of instructions describing how a resource currently residing on the origin server should be modified to produce a new version.

Therefore, the final result of the RESTful web services created in Tibco ESB for this project was:

  • POST /employee/id:  Creates a employee in the Payroll system;
  • PUT /employee/id: Broadcasts a message  so that all other systems replace a full employee data. Actually, this will only be used in the future in my project and we did not created it;
  • PATCH /employee/id: Broadcasts a message  so that all other systems update just a set of a employee’s data.

That’s all for today. I hope you now are able to make a better decision on when to use POST, PUT and PATCH when designing RESTful web services.