Similarities and differences between HTTP put and post methods
Written By
Harrison IfeanyichukwuStaff Software Engineer
Rest API Developers are well conversant with the GET and POST HTTP methods. But such cannot be said when it comes to non-commonly used HTTP methods such as the PUT, DELETE, PATCH, and HEAD methods.
As trivial as it sounds and to understand a candidate's broad knowledge of REST services, tech companies ask candidates to explain the differences between Post and Put methods or Put vs Patch Methods.
It is common to see junior developers overload the Post HTTP method in Rest applications due to their ignorance of other methods intended for such use cases.
In developing REST APIs, developers are tasked with structuring the API endpoints to accurately represent the application resources in a well-organized and understandable structure.
To do so, one must understand what are the Six Rest Architectural Constraints, understand the HTTP verbs, and the appropriate use of HTTP methods.
This article explains in-depth the important differences and similarities between the POST and PUT methods. The report also dives deep into the concept and architectural design of REST Applications.
The Six REST Architectural Constraints
A well-written and organized REST API conforms to the six REST architectural constraints and standards. The six REST Architectural constraints are:
- Client-server architecture
- Statelessness
- Cache-ability
- Layered System
- Code on demand (optional)
- Uniform Interface
The 6th constraint, Uniform Interface, touches on our topic. The uniform interface constraint is fundamental to RESTful applications' design. We see various kinds of content or resources on today's web, such as HTML files, image files, videos, audios, pdf, etc.
All these resources reside on the server and can be called server resources, application resources, or web resources. These resources have to be uniquely identified using URLs without misrepresentation.
Web resources are exposed and made available to clients via operations referred to as HTTP methods or verbs in a stateless form.
Using any HTTP methods, web clients such as web browsers can perform various kinds of operations on web resources by sending HTTP requests to servers, including resource retrieval, storage, deletion, updates, etc.
HTTP Methods
HTTP Methods are also known as HTTP verbs. As you know, a verb is a doing word, an action word.
Utilizing the understanding of a verb, HTTP Methods are standardized names that explain the action to be carried out in an HTTP operation. While HTTP methods state the actions to be performed, HTTP status codes convey the result of the operation back to the client.
Below are the 8 HTTP methods in use today:
- GET
- POST
- PUT
- DELETE
- HEAD
- OPTIONS
- CONNECT
- TRACE
The first four in the list, namely the GET, POST, PUT, and DELETE methods, are crucial and widely used in developing RESTful APIs.
Get and DELETE methods or operations are straightforward. HTTP clients use the GET method to retrieve resources from an HTTP server. HTTP Get requests have no side effects. The client can get the resource as many times as possible without affecting the state of the connected server.
DELETE Method: When a web client performs a DELETE operation on a specific server resource, it asks the server application to delete the resource identified by the request URL.
Unlike the GET method, DELETE requests have side effects, and as such, the requesting client may need to have the authentication and authorization to send the request.
With all that said, let's now look at the POST and PUT methods. When should one use one of the Put or Post methods, and how are they different? What are the similarities between the Post and Put methods?
Before going into details on the differences and similarities between the Post vs. Put methods, let me quickly discuss the Origin of the Web and the REST architecture.
Client-Server architecture. Communication is stateless. Application state is kept on the client and sent to the server for all requests.
Origin of the Web and REST Architecture
The World Wide Web began in 1989. Sir Tim Berners-Lee invented the World Wide Web in 1989. By October of 1990, Tim had written the three fundamental technologies that remain the foundation of today's web:
- HTML - this is the language of the web
- URI - Uniform Resource Identifier uniquely identifies resources on the web
- HTTP - Hypertext transfer protocol defines the protocol for the transfer of resources on the web
It is worth mentioning that Tim began his work working on a NeXT computer, one of Steve Jobs' products. The founder of Apple. Tim did not invent the internet; the internet was already existing when he started his work.
According to Tim, the internet fathers are Vint Cerf and Bob Kahn, who defined the internet protocol. Tim also developed the first GUI web browser and called it the WorldWideWeb. It ran on the NeXT computer. He later renamed it Nexus.
REST is an acronym that stands for representational state transfer. American computer scientist Roy Thomas Fielding created REST. Roy Thomas Fielding also cofounded the Apache HTTP Server Project.
Fielding developed the REST architecture in parallel with HTTP 1.1. The REST architecture aims for performance, supporting intermediate or layered systems between the client and the server, such as proxies, firewalls, and gateways.
RESTful applications are stateless, providing a set of uniform resource identifiers and request operations possible on those resources. Web resources can be HTML files, images, audio files, videos, scripts, Stylesheet files, etc.
Properties of HTTP Methods
To help us understand the similarities and differences between the POST vs PUT methods, we need to look into the characteristics or properties of HTTP methods.
HTTP Methods are categorized into 3 based on the properties or characteristics of HTTP methods:
- Idempotent Methods
- Cacheable Methods
- Safe Methods
In addition to the three, we can also look at two other characteristics of HTTP methods.
- Request Payload: Does the operation accept a request body?
- Response Payload: Does the operation allow sending a response body?
1. Safe HTTP methods
An HTTP method is considered safe if its semantics is essentially read-only. That is to say, the origin server is not expected to carry out any state changing operation while responding to the request.
It is just a specification and, as such, does not prevent the server application from running any logic that might lead to some side effects when handling the request, but a well-implemented REST API should adhere to this specification.
GET, HEAD, and OPTIONS methods are good examples of safe HTTP methods.
2. Cacheable HTTP methods
A cacheable HTTP method indicates that responses to them are allowed to be stored for future reuse. Web content caching and cache negotiations are a big topic of their own.
Servers should specify whether a response should be cached, how long it should be cached, and in what circumstances should it be revalidated.
3. Idempotent HTTP methods
An HTTP method is considered Idempotent if the intended effect on the server on multiple identical requests with that method produces the same effect as a single identical request.
When multiple identical requests with a given method leave the server in the same state, like a single identical request with the given method, such a request method is considered Idempotent.
GET and DELETE HTTP methods are good examples of Idempotent methods. The first request will delete the resource, probably a database user. Other subsequent requests will do nothing, returning a possible 404 response code.
DELETE /users/1 => response code 200
DELETE /users/1 => response code 404The required effect is that the user gets deleted. In all identical requests made, no matter how many times, the database state will remain the same, just as if it had only one request made against it.
The PUT method is idempotent, but the POST method is not. This particular characteristic will help us understand the differences between the PUT and POST methods.
HTTP PUT Method
The simplest way to explain the PUT method is that PUT requests instruct that the target resource state be created or replaced with the representation enclosed in the request payload.
If the origin server does not have a current representation for the target resource, it is created. If not, it is updated with the data given to reflect the new state. One important thing here is that the target resource identity i.e the URI is known by the client before the request is issued.
The PUT method is Idempotent such that multiple identical requests end up with the same result.
HTTP POST Method
Unlike the PUT method, the POST method instructs that the target resource processes the representation enclosed in the request payload according to its semantics or discretion.
It is like a postal service.
The POST and PUT HTTP method's key difference is that the representation enclosed in the request is handled by the target resource in the POST method. In contrast, for a PUT method, the target resource is to be created or replaced with the representation enclosed in the request.
To illustrate this, let us look at a User management system—an SQL database where we store users of an application. The database uses an auto-incrementing integer for user identification. It stores the user's first name and last name, as well as an email address.
CREATE TABLE users (
id INT NOT NULL AUTO_INCREMENT PRIMARY KEY,
first_name VARCHAR(255),
last_name VARCHAR(255),
email VARCHAR(255) UNIQUE
)With the above database created. We would need to expose API endpoints that will allow us to create a user, retrieve a user, update a user, delete a user, and even retrieve multiple users.
No | Description | Method | Endpoint | Idempotent |
|---|---|---|---|---|
1 | Create a user | POST | /users | No |
2 | Retrieve a user with a given id | GET | /users/{id} | Yes |
3 | Update a user with a given id | PUT | /users/{id} | Yes |
4 | Delete a user with a given id | DELETE | users/{id} | Yes |
We exposed the POST method for creating a user by looking at the API definitions because we do not know its URI. The created user's URI depends on the assigned database id, which is application dependent. The client does not know the id of the user to be created.
If we make multiple POST requests to the /users API endpoint with the same data, we will create multiple users; hence, POST requests are not Idempotent.
When updating a user entry, we exposed the PUT method because we know the user whose data is updated.
No matter how many times we update the user data by hitting the /users/{id} with the same payload, we will have the same intended result. Hence, PUT requests are Idempotent.
Today, many APIs use the POST method even when the PUT method is the appropriate method for such use cases. Part of the reason is that HTML Forms does not support any other HTTP methods that are not GET or POST.
To achieve a well structured RESTful API, you must learn to represent every resource in your application using URLs. I do not need to send the object or resource id to process in the request payload; it should be designed and built into your API URLs.
Such API endpoints, where every resource can be uniquely identified with URIs without request payloads, are always SEO friendly.
POST vs PUT methods, Similarities and differences
The POST and PUT HTTP methods have some characteristics in common. Both are unsafe methods as they create or update something on the server and both expect request payloads.
Despite some similarities, The POST and PUT HTTP methods have some differences. While the PUT method is considered Idempotent by design and intention, POST requests are not.
Also, Successful PUT requests do not allow for response payload, unlike POST methods. PUT requests are also not cacheable, while POST requests can be cached if cache information in the response payload allows it if provided.
POST | PUT | |
|---|---|---|
Safe | No | No |
Idempotent | No | Yes |
Cacheable | Yes | No |
Allows Entity Body in Request | Yes | Yes |
Allows Entity body in Response | Yes | No |
The similarities and differences between the Post and Put http method is summarized in the table above.