Rest API, PUT vs POST requests, differences and similarities

Harrison Ifeanyichukwu
By Harrison Ifeanyichukwu

Rest API Developers are well conversant with the use of the GET and DELETE HTTP methods. But many seem confused about the differences between the PUT and POST HTTP methods and when to use them.

A look at differences and similarities between PUT and POST HTTP methods

Rest API Developers are well conversant with the use of the GET and DELETE HTTP methods. But many seem confused about the differences between the PUT and POST HTTP methods and when to use them.

In developing REST APIs, developers are tasked with structuring the API endpoints to accurately represent the application resources in a well organised and understandable structure.

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:

  1. Client-server architecture
  2. Statelessness
  3. Cacheability
  4. Layered System
  5. Code on demand (optional)
  6. 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 in today's web, such as HTML files, image files, videos, audios, pdf,'s and others.

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

Below are the 8 HTTP methods or verbs:

  1. GET
  2. POST
  3. PUT
  4. DELETE
  5. HEAD
  6. OPTIONS
  7. CONNECT
  8. TRACE

The first four in the list, namely the GET, POST, PUT and DELETE methods, are crucial and widely used in developing RESTful API.

Get and DELETE methods or operations are straightforward to understand. When a web client performs a GET operation on a specific server resource, it asks the server application to retrieve and return the specified resource identified by a given and unique URL.

When a web client performs a DELETE operation on a specific server resource, it asks the server application to delete the resource identified by a given and unique URL to perform such an operation.

DELETE requests have side effects, and as such, the requesting web client may need some authentication and authorization to carry out such operation.

But what about POST and PUT? When do we use them, how are they different? Before going into details on those two HTTP methods, let me quickly talk about 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:

  1. HTML - this is the language of the web
  2. URI - Uniform Resource Identifier uniquely identifies resources on the web
  3. 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, which he called WorldWideWeb, that 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 and many others.

Properties and Classification of HTTP Methods

To help us understand the similarities and differences between the POST and PUT methods, we need to look into the characteristics or properties of HTTP methods in general.

Based on the properties or characteristics of HTTP methods or verbs, they can be categorized as follows:

  1. Idempotent Methods
  2. Cacheable Methods
  3. Safe Methods

In addition to the three, we can also look at two other characteristics of HTTP methods.

  1. Request Payload: Does the operation allow for request payload?
  2. Response Payload: Does the operation allow for a response payload?

1. Safe HTTP methods

According to the RFC specification, The Request 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. Well implemented REST API should adhere to the specification.

GET, HEAD, and OPTIONS methods are good examples of safe HTTP methods.

2. Cacheable HTTP methods

According to the RFC specification, Request methods can be defined as "cacheable" to indicate that responses to them are allowed to be stored for future reuse. Web content caching and cache negotiations is 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

According to this RFC specification, A Request 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 404

The 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.

PUT and POST Methods explained

let's dive deeper and establish clear explanations of the PUT and POST HTTP methods. There similarities and differences.

The PUT HTTP 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 to reflect the new state. One important thing here is that the target resource identity, 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. This might not sound clear enough, but soon it will be made clear sense.

The POST HTTP 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.

Sample API endpoints for a user management application

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.

Similarities between POST and PUT methods

The POST and PUT HTTP methods have some characteristics in common. Both are unsafe methods as they actually create or updates something on the server.

Both methods expect request payloads; else, it is not very sensible to make such requests.

Differences between POST and PUT methods

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.

Comparison between POST and PUT HTTP methods

Method

POST

PUT

Safe

No

No

Idempotent

No

Yes

Cacheable

Yes, if cache response headers allow

No

Accepts Request Payload

Yes

Yes

Allows Response Payload

Yes

No