What does the PUT method accomplish in an API?

The PUT method in an API is primarily used to update existing records or to create new records when a record with the specified identifier does not already exist. This action is commonly referred to as an "upsert," which stands for update or insert. When a client sends a PUT request to a specific URL, it is typically submitting a complete representation of the resource that it wants to update. If the resource is found at that URL, it will be updated with the new data; if it is not found, a new resource will be created using the provided information.

The key distinction that makes the PUT method suitable for upserting lies in its idempotency. Multiple identical requests should result in the same state of the resource, ensuring that whether the record exists or not, the final outcome is consistent. This makes it a powerful method in RESTful services where maintaining resource states is crucial.

In contrast, other methods listed, such as those for querying, creating, or deleting records, do not align with the fundamental operation of the PUT method. Queries are typically done using the GET method, new records are usually created with the POST method, and deletions are accomplished using the DELETE method.