Designing REST API → HTTP API Request Flow and HTTP Status Codes

Designing a RESTful API involves creating a structured and predictable flow for handling client requests and returning appropriate HTTP status codes to indicate the result of each request.

HTTP API Request Flow

A typical HTTP API request flow involves several steps:

1. Client Initiates Request:

   • The client sends an HTTP request to the server. The request includes an HTTP method (GET, POST, PUT, DELETE), a URL, headers, and sometimes a body.

2. Server Receives Request:

   • The server processes the incoming request, including parsing the URL, headers, and body.

3. Server Processes Logic:

   • The server performs the necessary business logic based on the request. This may involve interacting with a database, performing calculations, or querying other services.

4. Server Sends Response:

   • The server generates an appropriate HTTP response and sends it back to the client. The response includes an HTTP status code, headers, and possibly a data body.

Example Flow:

• Client sends a GET request to https://api.example.com/users.

• Server retrieves the list of users from the database.

• Server sends back the list of users in a JSON format with a 200 OK status code.

HTTP Status Codes

HTTP status codes are critical for informing the client about the outcome of their request. Here are some commonly used categories:

1xx Informational:

• 100 Continue

2xx Success:

• 200 OK: The request was successful, and the server returned the requested data (e.g., for GET requests).

• 201 Created: The request was successful, and a new resource was created (e.g., for POST requests).

• 204 No Content: The request was successful, but there is no content to return (e.g., for DELETE requests).

3xx Redirection:

• 301 Moved Permanently: The resource has been moved to a new URL.

• 304 Not Modified: The resource has not been modified since the last request.

4xx Client Errors:

• 400 Bad Request: The request is malformed or contains invalid parameters.

• 401 Unauthorized: The client must authenticate itself to get the requested response.

• 404 Not Found: The requested resource could not be found.

• 409 Conflict: There is a conflict with the current state of the resource (e.g., duplicate data).

5xx Server Errors:

• 500 Internal Server Error: A generic server error occurred.

• 503 Service Unavailable: The server cannot handle the request due to temporary overload or maintenance.

By implementing these practices, you’ll build a structured and predictable RESTful API that effectively communicates the outcome of each request through appropriate HTTP status codes.