Activity 30: HTTP Status Codes

Understanding HTTP Status Codes in RESTful APIs

RESTful APIs, or Representational State Transfer APIs, are a popular architectural style for building web services. They rely heavily on the HTTP protocol for communication between clients and servers. A crucial part of this communication is the use of HTTP status codes, which provide information about the outcome of an API request. This document will explore the various HTTP status codes categorized by their meaning, providing examples of their usage in RESTful APIs.

1xx (Informational) - Request Received and Being Processed

These codes signal that the server has received the request and is processing it, but no final response is available yet.

100 Continue: The server has received the initial part of the request (headers) and is asking the client to send the remaining part (body). This is often used in POST requests to avoid sending a large body if the server is not going to accept it. [1]

1xx: Informational

Description: These status codes indicate that the request has been received and is being processed, but no final response is available yet.

• Example Code: 100 Continue

  • Use Case: Sent in response to an initial part of a request, indicating that the client should continue sending the request body.

  • Example Response:

      HTTP/1.1 100 Continue
    

2xx: Success

Description: These status codes indicate that the request was successful and that the server returned the expected response.

• 200 OK

  • Description: The request was successful, and the server returned the requested data.

  • Example Response:

      HTTP/1.1 200 OK
      Content-Type: application/json
    
      {
        "message": "Data retrieved successfully",
        "data": {...}
      }
    

• 201 Created

  • Description: The request was successful, and a new resource was created as a result.

  • Example Response:

      HTTP/1.1 201 Created
      Location: https://api.example.com/users/123
    
      {
        "message": "User created successfully",
        "userId": 123
      }
    

• 204 No Content

  • Description: The request was successful, but there is no content to send in the response.

  • Example Response:

      HTTP/1.1 204 No Content
    

3xx: Redirection

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

• Example Code: 301 Moved Permanently

  • Description: The requested resource has been permanently moved to a new URL.

  • Example Response:

      HTTP/1.1 301 Moved Permanently
      Location: https://api.example.com/new-url
    

4xx: Client Error

Description: These status codes indicate that there was an error with the request sent by the client.

• 400 Bad Request

  • Description: The request was invalid or cannot be understood by the server.

  • Example Response:

      HTTP/1.1 400 Bad Request
      Content-Type: application/json
    
      {
        "error": "Invalid request format"
      }
    

• 401 Unauthorized

  • Description: Authentication is required for the requested resource.

  • Example Response:

      HTTP/1.1 401 Unauthorized
      Content-Type: application/json
    
      {
        "error": "Authentication required"
      }
    

• 403 Forbidden

  • Description: The client does not have permission to access the resource.

  • Example Response:

      HTTP/1.1 403 Forbidden
      Content-Type: application/json
    
      {
        "error": "Access denied"
      }
    

• 404 Not Found

  • Description: The requested resource could not be found.

  • Example Response:

      HTTP/1.1 404 Not Found
      Content-Type: application/json
    
      {
        "error": "Resource not found"
      }
    

5xx: Server Error

Description: These status codes indicate that the server encountered an error while processing the request.

• 500 Internal Server Error

  • Description: The server encountered an unexpected condition that prevented it from fulfilling the request.

  • Example Response:

      HTTP/1.1 500 Internal Server Error
      Content-Type: application/json
    
      {
        "error": "An unexpected error occurred"
      }
    

• 503 Service Unavailable

  • Description: The server is temporarily unavailable, often due to maintenance or overload.

  • Example Response:

      httpCopy codeHTTP/1.1 503 Service Unavailable
      Content-Type: application/json
    
      {
        "error": "Service temporarily unavailable"
      }
    

Summary Table of HTTP Status Codes

{ "data": ... } | | 201 | Success | Resource created successfully. | HTTP/1.1 201 Created
{ "userId": 123 } | | 204 | Success | Request was successful; no content to return. | HTTP/1.1 204 No Content | | 301 | Redirection | Resource moved permanently to a new URL. | HTTP/1.1 301 Moved Permanently
Location: ... | | 400 | Client Error | Invalid request. | HTTP/1.1 400 Bad Request
{ "error": "Invalid request" } | | 401 | Client Error | Authentication required. | HTTP/1.1 401 Unauthorized
{ "error": "Auth required" } | | 403 | Client Error | Access denied. | HTTP/1.1 403 Forbidden
{ "error": "Access denied" } | | 404 | Client Error | Resource not found. | HTTP/1.1 404 Not Found
{ "error": "Not found" } | | 500 | Server Error | Internal server error. | HTTP/1.1 500 Internal Server Error
{ "error": "Unexpected" } | | 503 | Server Error | Service temporarily unavailable. | HTTP/1.1 503 Service Unavailable
{ "error": "Try again" } |

HTTP status codes are an integral part of RESTful APIs, providing essential information about the outcome of requests. Understanding these codes helps developers handle errors, implement proper user feedback, and create more robust APIs. By correctly utilizing status codes, developers can improve the client-server communication process and enhance user experience in their applications.