Quick rule of thumb for successful PUT responses

PUT is idempotent which means repeating the same request should not create a mess of duplicate resources unless your server is feeling dramatic and documents that behavior. The server must clearly say whether the resource was created updated or accepted for later work. No cryptic whispering allowed.

Use 201 Created when a new resource was made

If the client created a new resource by sending a PUT then respond with 201 Created. Include a Location header that points to the new resource URL and you may also return the new representation in the response body for convenience. Clients like being handed the truth right away.

Use 200 OK when you return the updated representation

When the server updated an existing resource and wants to give the client the fresh canonical view return 200 OK with the updated representation. This is handy for clients that want an immediate snapshot for display or caching without asking twice.

Use 204 No Content when you only need to acknowledge success

If the update applied and there is nothing useful to return choose 204 No Content. This keeps traffic small and honest and saves clients from parsing empty mystery bodies.

Use 202 Accepted for asynchronous work

If the update is queued for later processing return 202 Accepted and give the client a way to check progress such as a status URL provided in the Location header or in the response body. Tell them how to check back so they do not start yelling in support channels.

Headers matter more than most people admit

Consistent headers are the difference between a maintainable API and heroic guesswork by client developers. Always set an ETag when you support optimistic concurrency control and expect clients to use If Match headers when they try to update a known version. Use Content Location when the representation you return comes from a different URL than the request target.

Avoid mixed messages

• Do not return 200 OK with an empty body unless you enjoy causing confusion
• Do not omit Location when you create a resource
• Do not forget ETag when clients need safe concurrent updates

Practical tips for API designers

• Pick one primary successful response for PUT across your API and stick with it. Predictability beats cleverness
• Document your rule and include examples so client authors can stop guessing
• If you support asynchronous updates make the status check reliable and easy to poll or subscribe to

In short do not be coy. Decide whether PUT will return a representation or just a thumbs up and document the choice. Your future self and your users will thank you and your support inbox will be slightly less dramatic.