PUT Method

What is PUT Method?

PUT is a HTTP method most often used in RESTful APIs. Traditionally, PUT is used to update an existing resource with new data or create a resource if it doesn’t already exist. If the URI refers to an already existing resource, it is modified; if the URI does not point to an existing resource, then the server can create the resource with that URI.

Principles of PUT Method

• Idempotent: The PUT method is idempotent. This means that if the same PUT request is made multiple times, the result should be the same - the resource is updated once.

  Example:

PUT /api/books/1 HTTP/1.1
Host: www.example.com
Content-Type: application/json

{
  "title": "Updated Title",
  "author": "Updated Author"
}

No matter how many times you send this PUT request, the book with ID 1 will have the title "Updated Title" and author "Updated Author". The idempotent nature of PUT is crucial as it ensures that the server maintains a consistent state even if the client sends the same request multiple times.

• Update or Creation: PUT can be used to update an existing resource or create a new resource if it does not exist. This dual functionality of PUT is a key feature that differentiates it from other HTTP methods like POST, which is primarily used for creating new resources.

  Example for creating a new resource:

PUT /api/books/2 HTTP/1.1
Host: www.example.com
Content-Type: application/json

{
  "title": "New Title",
  "author": "New Author"
}

In this scenario, if the book with ID 2 does not exist, it will be created with the provided title and author. This feature of PUT makes it a versatile choice when you have scenarios where you may need to either create or update resources based on their existence.

Why use PUT Method?

PUT is vital when you need to modify an existing resource or create a new resource if it doesn’t already exist. It provides a method to manage resources on the server and ensure data consistency through its idempotent nature. The PUT method is typically used in scenarios where the client is allowed to determine the resource identifier, like the URI, of the new or updated resource.

Understanding the Benefits of PUT Method

• Idempotency: The idempotent nature of PUT ensures that multiple identical requests have the same effect as a single request, promoting consistency and reliability. This is particularly beneficial in network environments where requests may be retried or duplicated, ensuring that such operations do not result in unintended side effects.

• Explicit: PUT is explicit in its function to update or create resources, making it easy to understand and use correctly. This explicitness helps in creating self-descriptive and intuitive APIs.

• Control: It provides control to the client over the resource it needs to update or create. This control allows the client to manage resources on the server effectively.

How does PUT Work?

The operation of the PUT method involves the following steps:

1. Client Sends a Request

   The client sends an HTTP request to the server with the PUT method, specifying the resource's URI and the data to update or create the resource.

PUT /api/books/1 HTTP/1.1
Host: www.example.com
Content-Type: application/json

{
  "title": "Updated Title",
  "author": "Updated Author"
}

Here, an attempt is made to update the book with ID 1 with a new title and author. This step is crucial as it initiates the interaction between the client and server, setting the stage for the update or creation of the resource.

1. Server Processes the Request

   The server processes the request, updates the specified resource or creates a new one, and prepares the response. This processing involves checking if the resource identified by the URI exists, and then either updating it with the provided data or creating a new resource with the given URI and data.

2. Server Sends a Response to the Client

   The server sends an HTTP response to the client, indicating the result of the request.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "title": "Updated Title",
  "author": "Updated Author"
}

The server confirms the update and reflects the changes in its response. This feedback to the client is essential as it informs the client of the outcome of its request.

Components of a PUT Request

A PUT request comprises several components:

• URI (Uniform Resource Identifier): The URI specifies where to send the request. For example: /api/books/1. It's like the address where the request should be delivered.

• Method: The HTTP method, which in this case is PUT. This method tells the server what action the client wants to perform.

• Headers: HTTP headers allow the client to pass additional information about the request and about itself, to the server. For instance, the Content-Type header tells the server the format of the data in the body.

Content-Type: application/json

Headers play a critical role in controlling how the request and response are handled by the server and client, respectively.

• Data: The data to update or create the resource, included in the request body.

{
  "title": "Updated Title",
  "author": "Updated Author"
}

The data is the core of the PUT request as it contains the new information that should be stored or updated on the server.

PUT Request Example

PUT requests are used to update or create resources on a server. Here are some examples showing how PUT requests can be used:

• Updating an Existing Resource:

PUT /api/books/1 HTTP/1.1
Host: www.example.com
Content-Type: application/json

{
  "title": "Updated Title",
  "author": "Updated Author"
}

This PUT request updates the book with ID 1 on the server with a new title and author. The server processes the request, modifies the resource, and sends a confirmation response back to the client.

• Creating a New Resource:

PUT /api/books/2 HTTP/1.1
Host: www.example.com
Content-Type: application/json

{
  "title": "New Title",
  "author": "New Author"
}

This PUT request creates a new book with ID 2 on the server if it doesn’t already exist. The server processes the request, creates the resource, and sends a confirmation response back to the client.

Conclusion

The PUT method is a powerful HTTP method used to update or create resources on a server. Its idempotent nature ensures data consistency, making it a reliable choice for developers.

Learn about other methods such as POST, GET and DELETE.