PUT Method in REST API Explained with Examples

The PUT method in REST API is used to create or replace a resource at a specific URI. When a client sends a PUT request, it provides the complete representation of the resource that should exist after the operation finishes.

Unlike the POST method, PUT is idempotent. Sending the same PUT request multiple times produces the same result as sending it once.

This predictable behavior makes PUT a common choice for updating user profiles, application settings, inventory records, and other resources where the client already knows the resource identifier.

What Is the PUT Method in REST API?

The PUT method is an HTTP request method defined by the HTTP Semantics specification. It tells the server to store the representation included in the request body as the current state of the target resource.

In simple terms, PUT replaces the existing version of a resource with the new version sent by the client.

For example, if a user profile already exists and you send a PUT request containing updated user information, the server replaces the existing profile with the data provided in the request.

PUT is one of several REST API methods used to interact with resources over HTTP.

PUT method in REST API

How the PUT Method Works in REST API

PUT operates on a specific resource in REST API. The client identifies the resource through a URI and sends the complete resource representation in the request body.

The server then validates the request and updates or creates the resource accordingly.

Anatomy of a PUT Request

A typical PUT request contains the following components:

1. HTTP Method

   • PUT

2. Resource URI

   • The unique endpoint that identifies the target resource.
   • Example: /api/users/123

3. Headers

   • Metadata about the request.
   • Common headers include:
     • Content-Type
     • Authorization
     • If-Match

4. Request Body

   • The complete resource representation.
   • Usually formatted as JSON.

If you want to understand these components in more detail, review the anatomy of a REST API request.

Example of a PUT Request

The following request updates an existing user profile:

PUT /api/users/123 HTTP/1.1
Content-Type: application/json

{
  "name": "Alice Johnson",
  "email": "alice.johnson@example.com",
  "age": 31
}

After the request succeeds, the server stores the new resource representation as the current state of user 123.

Why the PUT Method Is Idempotent

One of the most important characteristics of PUT is idempotency.

An idempotent operation produces the same result regardless of how many times the exact same request is repeated.

Consider the following request:

{
  "name": "Alice Johnson",
  "email": "alice.johnson@example.com",
  "age": 31
}

The first PUT request updates the resource.

If the same request is sent again, the resource remains unchanged because the desired state already exists.

This behavior is especially useful in distributed systems where network interruptions can cause requests to be retried automatically.

For a formal definition of idempotency, see the MDN Idempotent Glossary.

Common Use Cases for PUT Requests

PUT is commonly used when the client knows the exact resource it wants to modify.

Typical use cases include:

• Updating user profiles
• Replacing customer records
• Updating product information
• Modifying application settings
• Synchronizing records between systems
• Updating device configurations
• Managing infrastructure resources through APIs

Many cloud providers and enterprise APIs rely heavily on PUT operations because they provide predictable and repeatable behavior.

HTTP Response Codes Returned by PUT

A PUT request can return different HTTP status codes depending on the result.

200 OK

Returned when the resource is successfully updated.

The response may contain the updated resource representation.

201 Created

Returned when the resource did not previously exist and was successfully created.

The server may include the new resource location in the Location header.

204 No Content

Returned when the update succeeds but the server does not return a response body.

This is a common response for REST APIs.

400 Bad Request

Returned when the request contains invalid data or malformed syntax.

401 Unauthorized

Returned when authentication credentials are missing or invalid.

Learn more about REST API authentication and authorization.

404 Not Found

Returned when the requested resource does not exist.

409 Conflict

Returned when the update conflicts with the current state of the resource.

412 Precondition Failed

Returned when conditional request headers such as If-Match fail validation.

For a deeper understanding of HTTP status responses, see HTTP Status Message in REST API.

PUT vs POST vs PATCH

Developers often confuse PUT, POST, and PATCH because all three can modify data.

The differences become clearer when you look at how each method behaves.

When to Use PUT

Use PUT when:

• You know the resource URI
• You want to replace the entire resource
• You need idempotent behavior

When to Use POST

Use POST when:

• Creating a new resource
• The server generates the resource identifier
• Idempotency is not required

Learn more in the POST Method in REST API guide.

When to Use PATCH

Use PATCH when:

• Only specific fields need updating
• You want to avoid sending the entire resource
• Partial modifications are sufficient

Learn more in the PATCH Method in REST API guide.

Best Practices for Using PUT Requests

Send the Complete Resource Representation

PUT is designed for full resource replacement.

Include all fields that should exist after the update completes.

Validate Incoming Data

Validate request payloads before updating resources.

Input validation helps prevent data corruption and security issues.

Use Optimistic Concurrency Controls

In production systems, multiple users may update the same resource simultaneously.

Using ETags and the If-Match header helps prevent accidental overwrites.

The MDN ETag documentation provides a detailed explanation of how ETags work.

Return Appropriate Status Codes

Use response codes that accurately reflect the outcome of the request.

This makes API behavior more predictable for consumers.

Document API Contracts Clearly

Clearly document:

• Required fields
• Validation rules
• Response codes
• Error formats

Good API documentation reduces integration issues and improves developer experience.

Frequently Asked Questions

What is the PUT method in REST API?

The PUT method updates or creates a resource at a specific URI by replacing its existing representation with the data provided in the request body.

Is PUT always idempotent?

PUT is defined as idempotent by HTTP semantics. Repeating the same PUT request should produce the same outcome.

However, poor server-side implementations can violate this behavior, so API developers should design endpoints carefully.

Can PUT create a resource?

Yes.

If the target resource does not exist and the server allows it, a PUT request can create the resource and return 201 Created.

Can I use PUT for partial updates?

Technically some APIs allow it, but it is generally not recommended.

Use the PATCH Method in REST API when updating only specific fields.

How does PUT handle concurrent updates?

Many APIs use ETags and conditional requests with the If-Match header.

This prevents one client from accidentally overwriting changes made by another client.

Is PUT part of HTTP or REST?

PUT is an HTTP method.

REST APIs use HTTP methods such as:

• GET
• POST
• PUT
• PATCH
• DELETE
• HEAD

To understand the relationship between REST and HTTP, read How REST API Is Related to HTTP.

Key Takeaways

• PUT replaces the entire state of a resource.
• PUT is idempotent by design.
• Clients typically provide the full resource representation.
• PUT can update existing resources and sometimes create new ones.
• PATCH is usually a better choice for partial updates.
• ETags and conditional requests help prevent update conflicts.
• Correct status codes improve API usability and reliability.