PUT for full replacement in Rest API

Introduction

PUT is used to completely replace a resource on a server with new data. It updates everything about that resource.

You want to update all details of a user profile at once.

Replacing a whole document or file on a server with a new version.

Updating a product's full information in an online store.

Changing all settings of a device stored on a server.

Syntax

Rest API

PUT /resource/{id} HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "field1": "new value",
  "field2": "new value"
}

PUT replaces the entire resource at the given URL.

If the resource does not exist, PUT can create it.

Examples

This replaces the user with ID 123 completely with the new name and email.

Rest API

PUT /users/123 HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "name": "Alice",
  "email": "[e-mail]"
}

This replaces all details of product 456 with new values.

Rest API

PUT /products/456 HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "name": "New Product",
  "price": 19.99,
  "stock": 100
}

Sample Program

This Python program sends a PUT request to replace the post with ID 1 on a test API. It updates the title and body fully.

Rest API

import requests

url = 'https://jsonplaceholder.typicode.com/posts/1'

new_data = {
    "userId": 1,
    "id": 1,
    "title": "Updated Title",
    "body": "This is the updated body of the post."
}

response = requests.put(url, json=new_data)

print('Status code:', response.status_code)
print('Response JSON:', response.json())

Important Notes

PUT replaces the entire resource, so missing fields may be removed.

Use PATCH if you want to update only some fields without replacing everything.

Always send the full resource data with PUT to avoid losing information.

Summary

PUT fully replaces a resource at the given URL.

It can create the resource if it does not exist.

Use PUT when you want to update all fields of a resource at once.