HTTP Status Codes in RESTful APIs

HTTP status codes are crucial for a client, such as a browser or application, to communicate with a server. They represent standardized messages that identify the outcome of an API call and help developers and applications understand what is happening in the background. Status codes are classified according to their purpose, and each class gives information about the type of response.

The correct use of HTTP status codes in RESTful APIs allows developers to design systems easier to debug, maintain, and use. Below is a detailed explanation of the different subcategories of HTTP status codes, the objectives they serve, and examples of where and how they are used.

1xx Informational

This is the code indicating that the server has received a request and continues processing - it hasn't completed yet. These are not commonly used in the RESTful APIs but very useful in some specific situations, such as handling large payloads.

• Example: 100 Continue

  • When Used: The server acknowledges the initial part of a request and informs the client to proceed with sending the remainder, usually in cases of large file uploads.

  • Response Example:

      httpCopy codeHTTP/1.1 100 Continue
    

2xx Success

These codes indicate that the client's request was successfully received, understood, and processed by the server.

200 OK

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

• Response Example:

    httpCopy codeHTTP/1.1 200 OK
    Content-Type: application/json
  
    {
        "id": 1,
        "name": "John Elnar"
    }
  

201 Created

• When Used: The server successfully created a new resource as a result of the request.

• Response Example:

    httpCopy codeHTTP/1.1 201 Created
    Location: /users/1
    Content-Type: application/json
  
    {
        "id": 1,
        "name": "Isaac Elnar"
    }
  

204 No Content

• When Used: The request was successful, but there’s no data to return in the response body (e.g., after deleting a resource).

• Response Example:

    httpCopy codeHTTP/1.1 204 No Content
  

3xx Redirection

These codes indicate that the client must take additional action to complete the request, such as following a redirect to a different location.

301 Moved Permanently

• When Used: The requested resource has been permanently moved to a new URI.

• Response Example:

    httpCopy codeHTTP/1.1 301 Moved Permanently
    Location: https://example.com/new-uri
  

4xx Client Error

This category indicates that there was an issue with the client’s request, such as incorrect input or unauthorized access. These errors typically require the client to take corrective action.

400 Bad Request

• When Used: The server cannot process the request due to invalid syntax or parameters provided by the client.

• Response Example:

    httpCopy codeHTTP/1.1 400 Bad Request
    Content-Type: application/json
  
    {
        "error": "Invalid input",
        "message": "Username is required."
    }
  

401 Unauthorized

• When Used: The client needs to authenticate itself to gain access to the requested resource.

• Response Example:

    httpCopy codeHTTP/1.1 401 Unauthorized
    Content-Type: application/json
  
    {
        "error": "Unauthorized",
        "message": "Invalid API key."
    }
  

403 Forbidden

• When Used: The server understands the request but refuses to authorize it. This is usually due to insufficient permissions.

• Response Example:

    httpCopy codeHTTP/1.1 403 Forbidden
    Content-Type: application/json
  
    {
        "error": "Forbidden",
        "message": "You do not have access to this resource."
    }
  

404 Not Found

• When Used: The requested resource does not exist on the server.

• Response Example:

    httpCopy codeHTTP/1.1 404 Not Found
    Content-Type: application/json
  
    {
        "error": "Not Found",
        "message": "The resource could not be found."
    }
  

5xx Server Error

This category indicates that the server encountered an error while attempting to process the request. These errors are typically caused by server-side issues.

500 Internal Server Error

• When Used: A generic error indicating that the server encountered an unexpected condition that prevented it from fulfilling the request.

• Response Example:

    httpCopy codeHTTP/1.1 500 Internal Server Error
    Content-Type: application/json
  
    {
        "error": "Internal Server Error",
        "message": "An unexpected error occurred."
    }
  

503 Service Unavailable

• When Used: The server is temporarily unable to handle the request, often due to maintenance or being overloaded.

• Response Example:

    httpCopy codeHTTP/1.1 503 Service Unavailable
    Content-Type: application/json
  
    {
        "error": "Service Unavailable",
        "message": "The service is currently under maintenance. Please try again later."
    }
  

Conclusion:

HTTP status codes are very crucial to RESTful APIs because they allow for structured feedback on the client's side. Each code represents a specific scenario so that developers can handle the responses appropriately, hence leading to seamless interactions from the clients to the servers. Therefore, using these codes in an appropriate manner makes APIs more reliable, easier to debug, and gives a good experience towards end users.