Activity 30: HTTP Status Codes

Navigating the Landscape of HTTP Status Codes in RESTful APIs

RESTful APIs utilize HTTP status codes to provide clear and concise feedback to clients about the outcome of their requests. These codes act as a standardized language for communication between the server and the client, ensuring both parties understand the result of each interaction. This document will explore the most common HTTP status code categories and their associated codes, explaining their usage and providing illustrative examples.

1xx (Informational)

These codes indicate that the request has been received by the server and is being processed, but the final response is not yet ready.

100 Continue: The server has received the request headers and is asking the client to send the request body. This is typically used in POST requests to prevent the client from sending a large body if the server is not going to accept it.

Example Response:

HTTP/1.1 100 Continue

101 Switching Protocols: The server understands and is willing to comply with the client's request to switch protocols. This is often used for WebSocket upgrades.

Example Response:

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade

2xx (Success)

These codes indicate that the request was successful and the server has completed the requested action.

200 OK: The request was successful, and the server returned the requested data. This is the most common success code and is used for successful GET, PUT, PATCH, and DELETE requests.

Example Response:

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

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

201 Created: The request was successful, and a new resource was created as a result. This is typically used for POST requests.

Example Response:

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

{
  "id": 123,
  "name": "New User"
}

204 No Content: The request was successful, but there is no content to send in the response. This is often used for DELETE requests or when the server has processed the request but there is no data to return.

Example Response:

HTTP/1.1 204 No Content

3xx (Redirection)

These codes indicate that the client must take additional actions to complete the request, such as redirecting to another URL.

301 Moved Permanently: The requested resource has been permanently moved to a new URL. The client should update its bookmarks and links to point to the new URL.

Example Response:

HTTP/1.1 301 Moved Permanently
Location: /new/location

302 Found: The requested resource has been temporarily moved to a new URL. The client should use the new URL for this request, but future requests should still use the original URL.

Example Response:

HTTP/1.1 302 Found
Location: /temporary/location

304 Not Modified: The requested resource has not been modified since the last time the client fetched it. The client should use its cached copy of the resource.

Example Response:

HTTP/1.1 304 Not Modified

4xx (Client Error)

These codes indicate that the client has made an error in its request.

400 Bad Request: The request was invalid or cannot be understood by the server. This could be due to incorrect syntax, missing parameters, or invalid data.

Example Response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "Invalid request format"
}

401 Unauthorized: Authentication is required for the requested resource. The client must provide valid credentials to access the resource.

Example Response:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="My API"

403 Forbidden: The client does not have permission to access the resource, even if they are authenticated. This could be due to access restrictions or insufficient permissions.

Example Response:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "Access forbidden"
}

404 Not Found: The requested resource could not be found on the server. This could be due to a typo in the URL or the resource being deleted.

Example Response:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": "Resource not found"
}

5xx (Server Error)

These codes indicate that the server encountered an error and could not complete the request.

500 Internal Server Error: The server encountered an unexpected error and could not complete the request. This could be due to a bug in the server code, a database error, or a temporary system failure.

Example Response:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "error": "Internal server error"
}

503 Service Unavailable: The server is temporarily unavailable, often due to maintenance or overload. The client should try again later.

Example Response:

HTTP/1.1 503 Service Unavailable
Retry-After: 30

Conclusion:

Understanding HTTP status codes is crucial for developers building and consuming RESTful APIs. By utilizing these codes effectively, developers can ensure clear and consistent communication between clients and servers, leading to more robust, reliable, and user-friendly APIs.