Activity 30: HTTP Status Codes

HTTP Status Codes in RESTful APIs

HTTP status codes provide standard responses to indicate the outcome of API requests. These are grouped into categories based on the type of response they represent.

1xx (Informational)

Purpose: These codes indicate that the server has received the request and is processing it, but the client should wait for a final response.

Example:
100 Continue: Used during large file uploads to check if the client should continue the request or if there are issues before sending data.

2xx (Success)

Purpose: Indicate that the client’s request was successfully received, understood, and processed.

Common Status Codes

200 OK
- When Used: For successful GET, POST, PUT, DELETE, or PATCH requests when the server returns content.
- Example: A GET request fetching user data.
  Response:
```
  HTTP/1.1 200 OK
  Content-Type: application/json

  {
    "id": 1,
    "name": "Alice"
  }
```

201 Created

When Used: For POST requests where a new resource is created.

Example: Creating a new user.
Response:

  HTTP/1.1 201 Created
  Location: /api/users/1

  {
    "id": 1,
    "name": "Alice"
  }

204 No Content
- When Used: For successful requests where no content needs to be returned (e.g., DELETE or PUT requests).
- Example: Deleting a resource.
  Response:
```
  HTTP/1.1 204 No Content
```

3xx (Redirection)

Purpose: Indicate that additional steps are required to fulfill the request, often a redirection to a different URL.

Common Status Codes

301 Moved Permanently
- When Used: Indicates the resource has a new permanent URL.
- Example: Redirecting /old-resource to /new-resource.
302 Found
- When Used: Temporary redirection to another URL while keeping the original request method.

4xx (Client Error)

Purpose: Indicate issues caused by the client’s request, such as incorrect syntax or unauthorized access.

Common Status Codes

400 Bad Request
- When Used: The request is malformed or invalid (e.g., missing required parameters).
- Example: Sending invalid JSON data in a POST request.
  Response:
```
  HTTP/1.1 400 Bad Request

  {
    "error": "Invalid request payload"
  }
```
401 Unauthorized
- When Used: Authentication is required or failed (e.g., missing or invalid API key).
- Example: Accessing a private resource without a valid token.
  Response:
```
  HTTP/1.1 401 Unauthorized

  {
    "error": "Authentication required"
  }
```
403 Forbidden
- When Used: The client is authenticated but does not have permission to access the resource.
- Example: Attempting to delete admin-only data as a non-admin user.
404 Not Found
- When Used: The requested resource does not exist.
- Example: Accessing /api/users/9999 when no user with ID 9999 exists.

5xx (Server Error)

Purpose: Indicate problems on the server that prevent it from processing the request successfully.

Common Status Codes

500 Internal Server Error
- When Used: For unexpected server-side issues or unhandled exceptions.
- Example: A database connection failure during a request.
  Response:
```
  HTTP/1.1 500 Internal Server Error

  {
    "error": "An unexpected error occurred"
  }
```
503 Service Unavailable
- When Used: The server is temporarily unable to handle the request, often due to maintenance or overload.
- Example: API downtime for scheduled maintenance.
  Response:
```
  HTTP/1.1 503 Service Unavailable

  {
    "error": "The service is temporarily unavailable"
  }
```

Why and When These Codes Are Used

1xx: Rarely used in REST APIs but useful in scenarios like chunked transfers.
2xx: Used for successful operations. Choose specific codes like 200 for general success or 201 for resource creation.
3xx: Used when resources have moved to new locations.
4xx: Used to inform the client about request issues, promoting better error handling on the client side.
5xx: Indicates server-side issues, signaling the client that retrying the request later might help