Activity 30: HTTP Status Codes

HTTP status codes are essential in RESTful APIs as they communicate the outcome of an API request, letting the client know whether it was successful, requires additional actions, or failed due to an error.

1xx (Informational)

1xx codes indicate that the server has received the request and is continuing to process it, but no final response is available yet. They are rarely used in RESTful APIs but can be helpful for specific cases like switching protocols or handling long-running processes.

• 100 Continue: The server has received the request headers and expects the client to send the request body (used in scenarios with large payloads to minimize waste).

• 102 Processing: Used to inform the client that the request is being processed, but no final response is yet available. This can be useful in long-running requests.

2xx (Success)

2xx codes indicate that the request was successfully received, understood, and processed by the server. These are the most common status codes in RESTful APIs.

• 200 OK: The most commonly used success code. It indicates that the request was successfully processed and that the server is returning the requested resource. For example, a GET request to fetch a list of users will return 200 OK along with the data.

• 201 Created: This is used when a new resource has been created as a result of the request. It is common in POST requests (e.g., creating a new user or adding a new record). The server often includes the newly created resource's location in the response headers.

• 204 No Content: Used when the request was successful but there is no content to return. This is typically seen in DELETE requests when a resource is successfully deleted, but there is no body to send back.

3xx (Redirection)

3xx codes indicate that further action is needed by the client to complete the request, such as following a redirect to a different URL.

• 301 Moved Permanently: The requested resource has been moved to a new URL, and future requests should use this new location.

• 302 Found: The resource temporarily resides under a different URL, but the client should continue to use the original URL for future requests.

• 304 Not Modified: The resource has not been modified since the last request. This code is typically used for caching purposes to indicate that the client can use its cached version of the resource.

4xx (Client Error)

4xx codes indicate that the request contains bad syntax or cannot be fulfilled due to client-side issues. They inform the client that the problem lies with the request.

• 400 Bad Request: The server could not understand the request due to invalid syntax. This can occur when required fields are missing in the request body, or the input format is incorrect. It indicates that the client should modify the request and try again.

• 401 Unauthorized: The request requires user authentication, and the client has not provided valid credentials. This often happens when accessing protected resources without proper authentication tokens or login information.

• 403 Forbidden: The server understood the request but refuses to authorize it. Unlike a 401, the client’s credentials are known but they do not have permission to access the resource (e.g., trying to access admin-only content as a regular user).

• 404 Not Found: The requested resource could not be found on the server. This is typically returned when a client requests a resource that does not exist, such as a non-existent URL or an invalid resource ID.

5xx (Server Error)

5xx codes indicate that the server encountered an issue while processing the request. These errors generally reflect a problem on the server's side, not the client’s request.

• 500 Internal Server Error: A generic error indicating that the server encountered an unexpected condition preventing it from fulfilling the request. This could be due to a bug, an unhandled exception, or some other internal server issue.

• 503 Service Unavailable: The server is currently unavailable, often due to maintenance or overload. It typically indicates a temporary state, and the client is encouraged to try again later.

When and Why These Codes Are Used in RESTful APIs

1. 200 OK is used when the request was processed successfully and data is returned, such as in GET or PUT requests.

2. 201 Created is employed in POST requests when a new resource (like a database entry) is created, signaling the client that creation was successful.

3. 204 No Content is used for DELETE requests when a resource is successfully deleted, indicating there’s no additional information to return.

4. 301 and 302 are used when resources move or temporarily reside at different URLs. This helps maintain API versioning or URL changes without breaking client applications.

5. 400 Bad Request occurs when the client sends malformed or invalid data (e.g., missing required parameters in a form).

6. 401 Unauthorized and 403 Forbidden are used to protect sensitive resources, ensuring clients only access what they are permitted to.

7. 404 Not Found happens when a client requests non-existing resources, ensuring proper API structure.

8. 500 Internal Server Error and 503 Service Unavailable are server-side issues where the server either crashes due to a bug or is temporarily unable to process the request due to heavy load.