In this section you will learn about PUT Method, what is it, its benefits, components with PUT examples.
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
PUTmethod is idempotent. This means that if the same
PUTrequest is made multiple times, the result should be the same - the resource is updated once.
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:
PUTcan be used to update an existing resource or create a new resource if it does not exist. This dual functionality of
PUTis 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:
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?
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
Idempotency: The idempotent nature of
PUTensures 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.
PUTis 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:
Client Sends a Request
The client sends an HTTP request to the server with the
PUTmethod, specifying the resource's URI and the data to update or create the resource.
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.
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.
Server Sends a Response to the Client
The server sends an HTTP response to the client, indicating the result of the request.
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-Typeheader tells the server the format of the data in the body.
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.
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 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 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.
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.