HTTP Methods — GET, POST, PUT, PATCH, DELETE

GET: Retrieving Resources

The GET method is the bedrock of HTTP interaction, designed solely for the retrieval of data. When you issue a GET request, you are telling the server that you intend to read a representation of a resource without triggering any state changes or side effects on the server side. Because of this read-only constraint, GET is considered a safe method, meaning it can be invoked repeatedly without altering the underlying data. Furthermore, GET requests are idempotent; multiple identical requests will produce the same result every time. This property allows intermediaries like web browsers, proxies, and content delivery networks to cache responses aggressively, significantly reducing server load and improving response times for the end user. When designing your API, always use GET for fetch operations to leverage these built-in performance benefits of the HTTP protocol.

# Fetching a specific user resource
# Request: GET /users/123
response = requests.get('https://api.example.com/users/123')
if response.status_code == 200:
    user_data = response.json() # Resource retrieved successfully

POST: Creating New Resources

Unlike GET, the POST method is fundamentally non-safe and non-idempotent because it is intended to trigger state changes. You use POST when you want to submit data to be processed by a specific resource, typically resulting in the creation of a new subordinate entity. When a client sends a POST request, the server is responsible for determining the structure of the newly created resource and generating a unique identifier for it. Because the server processes the data and creates something new each time, sending the same POST request multiple times will likely result in multiple new resources being created, hence its non-idempotent nature. This method is the primary vehicle for form submissions, database injections, and any workflow where a unique creation event needs to be recorded accurately within your system architecture.

# Creating a new resource
# Request: POST /users
payload = {'name': 'Jane Doe', 'email': 'jane@example.com'}
response = requests.post('https://api.example.com/users', json=payload)
# Status 201 indicates a new resource was created

PUT: Complete Resource Replacement

PUT is unique because it defines an idempotent operation for updating resources. When you send a PUT request, you are providing a full representation of the resource that should replace the current version residing at the specific URI. Because you are sending the complete state, repeating the request has no further impact on the resource state once it has been updated; the end result is always the state defined in your request payload. This makes PUT an excellent choice for scenarios where the client holds the authority over the resource's entire configuration. If the resource does not exist at the specified location, some APIs use PUT to perform a creation operation, but it is standard practice to treat it primarily as an absolute replacement tool to avoid unintended partial updates.

# Replacing a resource entirely
# Request: PUT /users/123
full_user = {'name': 'Jane Doe', 'email': 'jane.new@example.com', 'active': True}
response = requests.put('https://api.example.com/users/123', json=full_user)

PATCH: Partial Resource Modification

PATCH provides a more granular approach to updates than PUT. While PUT requires sending the entire entity representation, PATCH allows you to send only the specific fields or properties that need to be modified. This is highly efficient when dealing with large objects where sending the full payload for a single field change would be wasteful of bandwidth. However, implementing PATCH requires careful consideration regarding idempotency. If the patch operation consists of a set of instructions, like incrementing a value, it may not be inherently idempotent. To ensure predictable behavior, developers often implement PATCH by applying atomic field updates that result in the same final state regardless of how many times the operation is executed in a short window. It is the preferred method for high-performance APIs requiring frequent, partial updates.

# Updating only specific fields
# Request: PATCH /users/123
update = {'email': 'updated.email@example.com'}
response = requests.patch('https://api.example.com/users/123', json=update)

DELETE: Removing Resources

The DELETE method is the final piece of the CRUD cycle, used to request that the server remove the resource identified by the target URI. From a design perspective, DELETE is considered idempotent. This means that whether you send the request once or ten times, the end state is the same: the resource no longer exists on the server. If the first request succeeds in deleting the resource, subsequent requests might return a status code indicating that the resource is already gone, but the overall system remains in the target state of 'deleted'. It is vital to ensure that DELETE operations are authenticated and authorized correctly, as they are destructive by nature. When building your API, always provide a clear confirmation or standard response code to signify that the deletion intent has been successfully acknowledged and processed.

# Removing a resource
# Request: DELETE /users/123
response = requests.delete('https://api.example.com/users/123')
# Status 204 indicates success with no content to return

Interview questions

All REST API Design interview questions →

Check yourself

Take the full REST API Design quiz →