CRUD mapping to HTTP Verbs
I recently came across a discussion as to how http verbs map with CRUD. Sounds simple, right? Well it ain’t that simple! Those minute details can make a large difference in API performance and as a developer we ought to have the complete knowledge of it.
What is CRUD?
It is an acronym for C - create, R - read/retrieve, U -update, D - delete- the four basic functions that are implemented in any relational DB applications. Each of it can map to a standard SQL statement, HTTP protocol method or Data Distribution Service (DDS). One can think of REST as the “CRUD for HTTP resources & more”- as long as one understands the difference between http resources and db records. REST is an API architecture which interacts with complex system whereas CRUD is a set of primitive operations which mostly manipulates data. In this blog we will be covering the different http verbs and how they map with CRUD operations.
HTTP verbs
There is a long list of http verbs but we will be talking primarily about POST, GET, PUT, PATCH, and DELETE.
< GET >
This Http method is used to read a representation of a resource. It should never modify any resources on the server and hence performing this action numerous time will not change the data. Therefore one expects the same response every time (unless & until it’s state is actually changed by other http methods)- which makes GET an idempotent method*.
* An idempotent HTTP method is an HTTP method that can be called many times without changing the server state. Idempotency is a fundamental property of the HTTP specification and must be adhered to guarantee web interoperability and scale.
GET returns a representation in XML or JSON and an HTTP response code of 200 (OK). In an error case, it most often returns a 404 (NOT FOUND) or 400 (BAD REQUEST). These responses to GET request are not just idempotent but cacheable* also. But these responses become stale once the data is changed via a method like PUT - it invalidates all cached GET or HEAD requests to same URI.
* A cacheable response is an HTTP response that can be cached, that is stored to be retrieved and used later, saving a new request to the server
< POST >
This method is used to create a new http resource of a specified type in REST environment. Upon successful creation, the server should return a header with a link to the newly-created resource, along with a HTTP response code of 201 (CREATED). A POST method can never be idempotent-it leads to server state change each time it is called. Making two identical POST requests will most-likely result in two resources containing the same information. If it were to be idempotent, the data needs to be present at server side in some form to get same response every time- which beats the definition POST! It can also be used to update an existing resource, if one wants to make use of its non -idempotency feature. Though in some case one would want to make a post request to be idempotent (like creating a new payment request) for which we can pass Idempotency-Key in headers, which is then checked in db by middleware before forwarding the request.
Responses to POST method are not cacheable, UNLESS the response includes appropriate Cache-Control or Expires header fields.
< PUT >
This http verb is mostly used for complete replacement of an existing resource URI. One of the constraints of PUT is that one need to pass the entire resource object with updated values and old values which one wants to retain. If object is passed partially, it updates the missing field as null, thus leading to data inconsistency! Nobody wants that, so be very careful while updating the data via PUT. In case of race conditions, where 2 request are updating the same resource, whichever request updates last- that state of object will be reflected. PUT comes handy while updating files or pdf etc at server- where one wants complete replacement. But what if the object to be updated is not present? In that case PUT creates a new one!
PUT is not a safe operation, in that it modifies (or creates) state on the server, but it is idempotent. In other words, if you create or update a resource using PUT and then make that same call again, the resource is still there and still has the same state as it did with the first call (unless & until your request is different this time for same URI) unlike POST which keeps on creating infinitely for same request if repeated. Therefore it is important to understand when to use POST or PUT for resource creation.
Along with updating the resource, it also invalidates the cached GET/HEAD requests as mentioned previously! PUT requests are not at all cacheable.
< PATCH >
PATCH come to escape when one wants to partially update the resources. Unlike PUT, one just have to send the updated fields in request and not the entire resource object. Since we are sending less fields in http request, the payload size reduces and one optimize the network bandwidth more efficiently.
But PATCH is neither safe nor idempotent. However, a PATCH request can be issued in such a way as to be idempotent, which also helps prevent bad outcomes from collisions between two PATCH requests on the same resource in a similar time frame. Collisions from multiple PATCH requests may be more dangerous than PUT collisions because some patch formats need to operate from a known base-point or else they will corrupt the resource. The client can use a strong ETag in an If-Match header on the PATCH request. PATCH request are not cacheable but can be made if specified in headers!
Support for PATCH in browsers, servers, and web application frameworks is not universal. IE8, PHP, Tomcat, Django, and lots of other software has missing or broken support for it .
There is often a debate as to what one should use for resource updation- PUT or PATCH? Well both are different and serves different use cases, now you know why!
< DELETE >
This http method is used to delete any existing resource of the system identified by a URI. HTTP-spec-wise, DELETE operations are idempotent. If you DELETE a resource, it’s removed. Repeatedly calling DELETE on that resource ends up the same: the resource is gone! Calling DELETE on a resource gives 200 (OK) or 204 (NO CONTENT), but calling it a second time or n number of times after first delete call it returns 404 (NOT FOUND) since it was already removed and therefore is no longer findable. This, by some opinions, makes DELETE operations no longer idempotent, however, the end-state of the resource is the same! Also DELETE is not cacheable.
Mapping with CRUD
There is a common misconception that CRUD has one to one mapping with http verbs. Which verb is best suited match for a CRUD operation depends totally on what use case we have at hand. One has to consider all the factors like idempotence, cache ability, method safety etc before making the final choice. Following are the possible mappings of http verbs with CRUD operations, but final decision is for the developer to make! SO CHOOSE WISELY :)
