Best HTTP Status Codes for PUT DELETE

For successful UPDATE (PUT) operations in REST APIs, the HTTP 200 OK status code should typically be returned when the operation completes successfully, while for successful DELETE operations, HTTP 204 No Content is the most appropriate response. These status codes follow REST conventions where 2xx codes indicate success, with 200 providing response body details for updates and 204 signaling successful resource removal without returning content.

Contents

• Understanding REST API Status Codes
• PUT Operations: Successful Updates
• DELETE Operations: Successful Deletions
• Alternative Status Codes and When to Use Them
• Best Practices for Implementation
• Common Mistakes to Avoid

Understanding REST API Status Codes

HTTP status codes are standardized three-digit numbers that indicate the result of an HTTP request. In REST APIs, these codes follow a hierarchical structure:

• 1xx: Informational responses
• 2xx: Successful responses
• 3xx: Redirection messages
• 4xx: Client errors
• 5xx: Server errors

For successful operations, REST APIs primarily use 2xx status codes, but the specific code chosen depends on the nature of the operation and the expected response from the server.

The HTTP/1.1 specification defines these status codes, and REST API design patterns have established conventions for their usage in different scenarios.

PUT Operations: Successful Updates

When a PUT operation successfully updates a resource, the server can return several status codes depending on the specific circumstances:

HTTP 200 OK

The most common response for successful PUT operations is HTTP 200 OK. This status code indicates that the request was successful and typically includes a response body containing the updated resource representation.

{
  "id": 123,
  "name": "Updated Product",
  "price": 29.99,
  "updated_at": "2024-01-15T10:30:00Z"
}

HTTP 204 No Content

In some cases, especially when the client doesn’t need the updated resource representation returned, a HTTP 204 No Content response can be used. This is common in update operations where the client already knows the expected state of the resource.

HTTP 201 Created

If the PUT operation creates a new resource (rather than updating an existing one), HTTP 201 Created should be returned with a Location header pointing to the new resource’s URI.

The key consideration for PUT operations is whether the client needs to receive the updated resource representation in the response body. If yes, use 200 OK; if not, 204 No Content is appropriate.

DELETE Operations: Successful Deletions

For DELETE operations, the response status codes are more straightforward:

HTTP 204 No Content (Recommended)

HTTP 204 No Content is the most appropriate status code for successful DELETE operations. This code indicates that the request was successful but the server doesn’t need to return a response body, which makes sense since the resource has been deleted.

The client should not expect any content in the response body when receiving a 204 status code.

HTTP 200 OK

Some implementations return HTTP 200 OK with a response body indicating successful deletion. While functional, this is less common and goes against the principle that DELETE operations shouldn’t return resource representations.

HTTP 202 Accepted

If the deletion is an asynchronous operation that requires time to complete, HTTP 202 Accepted can be returned. This indicates that the request has been accepted for processing but is not yet complete.

The general rule for DELETE operations is that HTTP 204 No Content is the standard and most appropriate response for successful synchronous deletions.

Alternative Status Codes and When to Use Them

HTTP 200 OK vs 204 No Content Comparison

Special Considerations

Conditional Updates and Deletions:
When using conditional requests (ETags, Last-Modified), different status codes apply:

• HTTP 412 Precondition Failed when conditions aren’t met
• HTTP 304 Not Modified for conditional GETs

Batch Operations:
For bulk operations, consider:

• HTTP 207 Multi-Status for partial success/failure scenarios
• HTTP 200 OK with detailed operation results

Best Practices for Implementation

Consistency is Key

Regardless of which status codes you choose, the most important practice is consistency across your API. All endpoints that perform similar operations should return the same status codes in similar circumstances.

Clear Documentation

Document your API’s status code behavior clearly, including:

• Which status codes each endpoint returns
• What each status code means in the context of your API
• Response body formats for successful operations

Use Proper Headers

Include appropriate headers with your responses:

• Content-Type header for responses with bodies
• Location header for resource creation (201)
• ETag header for conditional operations

Handle Edge Cases

Consider edge cases such as:

• Updating non-existent resources (return 404 Not Found)
• Deleting already-deleted resources (return 404 Not Found or 410 Gone)

Common Mistakes to Avoid

Inconsistent Status Codes

One of the most common mistakes is using inconsistent status codes for similar operations across different endpoints. This confuses API consumers and makes the API harder to use.

Returning Unnecessary Response Bodies

Avoid returning response bodies for DELETE operations or PUT operations where the client doesn’t need the updated representation. Use 204 No Content appropriately.

Overusing 200 OK

While 200 OK is safe, it’s not always the most appropriate choice. Consider whether 204 No Content would be better for operations where no meaningful response body is needed.

Ignoring HTTP Semantics

Don’t ignore the semantic meaning of status codes. Each code has a specific meaning according to the HTTP specification, and deviating from these established meanings can confuse API consumers.

Conclusion

• For successful PUT operations, use HTTP 200 OK when the client needs the updated resource representation, or HTTP 204 No Content when no response body is needed.
• For successful DELETE operations, always use HTTP 204 No Content as it indicates successful deletion without requiring a response body.
• Maintain consistency across your API and document your status code behavior clearly.
• Avoid common pitfalls like returning unnecessary response bodies or using inappropriate status codes that violate HTTP semantics.
• Consider the specific needs of your API consumers when choosing between 200 OK and 204 No Content for update operations.

By following these established REST API conventions, you’ll create APIs that are predictable, intuitive, and aligned with web standards that developers expect.

Sources

1. HTTP/1.1 Status Code Definitions - RFC 7231
2. REST API Tutorial - HTTP Methods
3. Mozilla Developer Network - HTTP status codes
4. Microsoft REST API Guidelines - Status Codes
5. Roy Fielding’s REST Dissertation