Updating APIs with HTTP Methods & JSON Patch
What are HTTP Methods
HTTP (HyperText Transfer Protocol) methods are a set of requests that enable APIs (Application Programming Interfaces) to perform CRUD (Create, Read, Update, Delete) operations.
Common HTTP Methods
POST
- The POST method is used to create new resources.GET
- This method is used to retrieve data.PUT
- The PUT method updates existing resources by replacing them entirely.PATCH
- This method only partially updates existing resources.DELETE
- The DELETE method is used to remove resources or data.
PUT VS PATCH
As mentioned, PUT and PATCH are conventional HTTP methods for updating resources. Now that we understand how these two update methods work let's consider their unique characteristics, including their advantages and disadvantages, security implications, and appropriate use cases.
PUT Advantages
It is idempotent, which means identical requests will have the same effect as a single request.
It is simple to implement as it sends the completed updated entity, making it easy for the server to handle requests.
The PUT method is transparent, as the state of resources on the server will always be the same as client requests.
PUT Disadvantages
The PUT method involves significant data transfer, especially when only parts of the resource require changes.
The client may replace resources, and there is a risk of unintentional data loss.
PUT requests are vulnerable to CSRF (Cross-Site Request Forgery) as they can alter the server's state.
PUT Use Case
The PUT method should be implemented when resources require updates by being replaced entirely or when the updates are not required frequently.
PUT Demo
Let us have a look at PUT in action. Below is a snapshot of a Roster system I am developing; let's say I want to change my work availabilities and have informed my manager. This is a snapshot of my existing records in the database:
Once the request is fulfilled, the manager will modify the availability and notice that my other records have been removed.
PUT request is appropriate when only the entire fields are required for updates, and situations like this will result in unintentional data loss. Without a backup record, the manager cannot retrieve the lost data. However, my manager has a photographic memory in this case and recreates my records.
PATCH Advantages
The PATCH method is more efficient as it only updates the required resource parts.
It is more flexible with other operations, such as appending to lists or partially updating when certain conditions are met.
PATCH Disadvantages
It is a more complex implementation as the server must handle requests to apply only partial updates.
PATCH requests can be used to modify resources the requester should not access.
PATCH Use Case
PATCH methods are suitable for applications that require frequent updates to targeted sections in the resource and where bandwidth usage is limited, such as mobile environments.
What is JSON PATCH
JSON PATCH is a format specifier that describes how to modify a JSON document by describing changes using a structured approach. This reduces the errors, allows atomic operations and simplifies the process as only the client's specific changes are sent instead of the entire JSON document.
Structure of JSON PATCH Document
The JSON PATCH document is a JSON array, each element describing a single operation. Below is the general structure of the JSON operation:
path
- This is a JSON pointer specifying the part of the document on which the operation will be executed.op
- A string describing the type of operation to be performed.value
- The new value to be used within the operation.
JSON PATCH Operations
add
- Add a value to the document.remove
- Remove a value from the document.replace
- Replace the current value with a new value.move
- Move a value to another specified path in the document.copy
- Copy a value to another specified path in the document.test
- Test that the provided value matches the specified value.
Advantages of JSON PATCH
An efficient approach that only sends specific changes rather than the entire document.
JSON PATCH has reduced bandwidth usage as only specific changes are sent, not the whole document, making it ideal for limited bandwidth environments.
JSON PATCH allows for precise modification; this reduces the risk of unintentional modification or data loss.
JSON PATCH & PATCH Method
Perhaps you're curious how JSON PATCH and the PATCH method relate. JSON PATCH employs the PATCH method to streamline and improve the precision of partial updates to resources.
PATCH Demo
This image represents a database snapshot from a user record in my roster management system. I forgot to inform my manager of my work availability. Utilising our knowledge, we can apply PATCH and JSON PATCH to modify the availability directly, rather than recreating the entire user profile. This allows the manager to update my availability while preserving my historical data.
PATCH is only ideal when partial sections must be altered and not appropriate when entire fields are required for updates like the PUT method.
Summary
Having established that PUT and PATCH are standard HTTP methods for updating resources, we should delve into their distinct attributes. This exploration will cover their respective benefits and drawbacks, the security considerations they entail, and the scenarios in which each method is most effectively utilised.
Subscribe to my newsletter
Read articles from Nabidul Islam directly inside your inbox. Subscribe to the newsletter, and don't miss out.
Written by
Nabidul Islam
Nabidul Islam
Hey, I am Nabidul. I am a Software Engineering student at the University of Technology Sydney (UTS). I love gaming with my friends, going to the gym, trying new foods & exploring new places. My passion for programming started in high school, and I decided to pursue a career in Software Engineering.