Handling HTTP Status Codes in a REST API (200 OK vs. 201 Created)

Handling HTTP status codes in a REST API can be tricky, especially when dealing with successful operations that create or modify resources. In this article, we will clarify the differences between HTTP status codes 200 and 201, providing a quick guide to help you understand when and how to use each of these codes effectively.

Understanding HTTP Status Codes

HTTP status codes are a standardized way for servers to communicate the result of a client's request. They are grouped into five classes:

1. 1xx: Informational
2. 2xx: Success
3. 3xx: Redirection
4. 4xx: Client Errors
5. 5xx: Server Errors

Here, we focus on the 2xx success class, specifically the 200 OK and 201 Created status codes.

200 OK: General Success

The 200 OK status code indicates that the request was successful, and the server returned the requested resource.

When to Use 200 OK

• GET Requests: When a resource is successfully retrieved.

  GET /users/123 HTTP/1.1
  Host: example.com

  HTTP/1.1 200 OK
  Content-Type: application/json

  {
    "id": 123,
    "name": "John Doe",
    "email": "john.doe@example.com"
  }

• PUT/PATCH Requests: When a resource is successfully updated.

  PUT /users/123 HTTP/1.1
  Host: example.com
  Content-Type: application/json

  {
    "name": "John Doe Updated"
  }

  HTTP/1.1 200 OK
  Content-Type: application/json

  {
    "id": 123,
    "name": "John Doe Updated",
    "email": "john.doe@example.com"
  }

• DELETE Requests: When a resource is successfully deleted (although some prefer 204 No Content).

  DELETE /users/123 HTTP/1.1
  Host: example.com

  HTTP/1.1 200 OK
  Content-Type: application/json

  {
    "message": "User deleted successfully"
  }

• POST Requests: When an action is successful but does not create a new resource (e.g., submitting a form that processes data without creating a new entity).

  POST /forms/submit HTTP/1.1
  Host: example.com
  Content-Type: application/json

  {
    "formField": "value"
  }

  HTTP/1.1 200 OK
  Content-Type: application/json

  {
    "message": "Form submitted successfully"
  }

201 Created: Resource Creation

The 201 Created status code indicates that the request was successful, and a new resource was created as a result.

When to Use 201 Created

• POST Requests: When a new resource is successfully created.

  POST /users HTTP/1.1
  Host: example.com
  Content-Type: application/json

  {
    "name": "Jane Doe",
    "email": "jane.doe@example.com"
  }

  HTTP/1.1 201 Created
  Location: /users/124
  Content-Type: application/json

  {
    "id": 124,
    "name": "Jane Doe",
    "email": "jane.doe@example.com"
  }

• PUT Requests: When a new resource is created at a specific URI.

  PUT /users/125 HTTP/1.1
  Host: example.com
  Content-Type: application/json

  {
    "name": "Sam Smith",
    "email": "sam.smith@example.com"
  }

  HTTP/1.1 201 Created
  Location: /users/125
  Content-Type: application/json

  {
    "id": 125,
    "name": "Sam Smith",
    "email": "sam.smith@example.com"
  }

Response Headers and Body

When using 201 Created, it’s important to include:

• Location Header: The URI of the newly created resource.

  Location: /users/124

• Response Body: A representation of the newly created resource.

  {
    "id": 124,
    "name": "Jane Doe",
    "email": "jane.doe@example.com"
  }

Tips for Using 200 OK and 201 Created

• Consistency: Use 200 OK for successful read, update, and delete operations. Use 201 Created specifically for successful creation operations.
• Clarity: Always include a Location header in 201 responses to guide clients to the newly created resource.
• Detail: Provide meaningful responses, including resource representations, especially in 201 responses to confirm creation details.

Conclusion

By understanding and correctly using these status codes, you can improve the clarity and effectiveness of your REST API, making it more intuitive for clients to interact with. Proper use of 200 OK and 201 Created helps ensure that your API communicates success in a clear and standardized way, enhancing the overall developer experience.