How to Differentiate Between Put and Post Request In Rest API
Tags: api, restapi, webdev, programming
Published: 2023-11-06 15:42:42

I remember asking myself this question when I started learning API methods. You are not alone, as many developers struggle to tell the difference between the POST and PUT methods when building and designing a system.

To understand this article better, it is important to understand the meaning of Rest API. REST (Representational State Transfer) is simply a style of software architecture. Easy! And, as described in a dissertation by Roy Fielding, REST is an “architectural style” that basically exploits the existing technology and protocols of the Web. 
While Restful API is typically used to refer to web services implementing such “architectural style” (REST).

Now that the concept of REST API is clear, RESTful web services use HTTP methods to communicate with clients. The HTTP method used by the client will determine how the server will respond to the request. The PUT and POST are examples of HTTP methods used in RESTful web services.

**Key Difference**

The PUT method is used to update an existing resource, while the POST method is used to create a new resource. What this simply means is that PUT is used for updates to existing data, while POST creates a new object for new data to be created.

**How It Works**

When the POST method is used to create a resource on the server, the resource is created as a subordinate resource to the URL that the POST method provides. For example, in a flight tracking system where users look up the status of an “American Airlines flight”, the URL will look like this:
`www.example.com/flights/AA123`

The PUT method, on the other hand, requires the exact URL of the resource to be updated. For example, to update the status of the flight, the PUT operation includes a JSON or XML payload to describe the new status.

```
PUT URL: www.example.com/flights/AA123
PAYLOAD: {"status": "ontime", "gate": "b12"}
```

It is a common occurrence in database-based applications that the exact URL of the resource is not known. The newly created resource is identifiable by a value that gets generated after the resource’s data is recorded.

An example of such an occurrence is a primary key-based identifier. If you need to create a resource that is subordinate to the URL provided, you should use a POST method, not a PUT method.

When you use the POST method, all the information needed to create a new resource is provided as JSON or XML in the request’s payload. REST demands that the new URL created be sent back to the calling program as a location header. This allows the calling program to use the PUT method for future updates.

This is why the difference between a PUT and POST method is often phrased as; to create an object, use a POST, while the PUT method should be used for updates.

**Idempotence**

Idempotent means that a certain operation can be applied many times without the result changing. 

PUT is idempotent, while POST is not idempotent. This simply implies that when you use the PUT method to call "create user” multiple times, you should still get one user as long as the value is the same. Multiple identical PUT requests will have the same effect as a single request.

In contrast, for POST requests, new records get created when duplicate data is sent.

**Status Code**

In a POST request, a new record gets created for each request, HTTP `201` is sent in response when this is done, and HTTP `409` if duplicates are not allowed. HTTP `200` is sent when the record gets updated, and HTTP `201` if the record is new.

For a PUT request, the server sends a `200 (OK)` or a `204 (No Content)` response to indicate successful completion of the request if there is no current representation of the data on the server.  HTTP `201` will be sent if a new resource is created.
 
Lastly, in this tutorial, you learned about REST and RESTful web services. You have looked at what distinguishes a PUT request from a POST request, their respective idempotency, and what response a server sends when any of them is executed.