What is the PUT method?

The PUT method

The HTTP PUT method has one job. It replaces the resource at a specific URL, or creates it if it doesn't exist yet.

Unlike POST, which says "Here is some data, server, please create a new item for me," PUT says "Take this exact data and place it at this URL."

A real-world analogy

Imagine you are updating your profile picture on a social media website.

• If you use POST (like creating a new post), the server might create a new URL every time: /photos/123, then /photos/124, etc.
• If you use PUT to /users/johndoe/profile-picture, you are saying "Make this image the profile picture at this exact URL." If a picture is already there, it gets overwritten. If there isn't one, it gets created.

The "upsert" behavior

Because PUT can both update an existing item and create a new item if it doesn't exist, it is often described as an "Upsert" operation (Update + Insert).

If you send a PUT request to /articles/10 and article #10 already exists, the server replaces article #10 with your new data. If it doesn't exist, the server might create a new article with the ID 10. That depends on the API design.

Full replacement

A critical rule of the PUT method is that it represents a full replacement of the resource.

If a User object has a name, email, and age, and you want to update just their age to 30 using PUT, you cannot just send { "age": 30 }.

You must send the entire representation of the user: { "name": "John Doe", "email": "[email protected]", "age": 30 }.

If you only send the age, a strict PUT implementation will delete the name and email fields or set them to null. You asked for a total replacement, and that is what you get.

Summary