REST API Request-Response Framework Models

🏷️ APIs and HTTP Requests / API Architecture Brief Recap

📚 All-in-One📖 Theory Only💻 Code Only

📖 Context Introduction

REST (Representational State Transfer) is an architectural style for designing networked applications. It relies on a stateless, client-server communication protocol—almost always HTTP. In a RESTful system, the client sends a request to a server, and the server sends back a response. Understanding the structure of these requests and responses is fundamental for any engineer working with APIs, as it forms the backbone of how systems communicate over the web.

⚙️ The Anatomy of a REST Request

Every REST request is composed of several key parts. When you interact with an API, you are essentially sending a message that includes:

HTTP Method (Verb): This tells the server what action to perform. Common methods include:
GET: Retrieve data (e.g., fetch a list of users).
POST: Create new data (e.g., add a new user).
PUT: Update existing data (e.g., replace a user's information).
PATCH: Partially update data (e.g., change only a user's email).
DELETE: Remove data (e.g., delete a user).
URL (Endpoint): The specific address on the server where the resource lives. For example, https://api.example.com/users.
Headers: Metadata sent along with the request. They provide context like authentication tokens (Authorization), the format of the data being sent (Content-Type), or the expected response format (Accept).
Body (Optional): The actual data payload sent with the request. This is common with POST and PUT requests. The data is often formatted as JSON (JavaScript Object Notation).

📊 The Anatomy of a REST Response

Once the server processes the request, it sends back a response. A standard response includes:

Status Code: A three-digit number indicating the result of the request. Common codes include:
200 OK: The request was successful.
201 Created: A new resource was successfully created (often used with POST).
204 No Content: The request was successful, but there is no content to return (often used with DELETE).
400 Bad Request: The server could not understand the request (e.g., malformed syntax).
401 Unauthorized: Authentication is required or has failed.
404 Not Found: The requested resource could not be found.
500 Internal Server Error: A generic error occurred on the server.
Headers: Metadata from the server, such as the format of the response data (Content-Type) or server information.
Body (Optional): The data returned by the server. For a successful GET request, this would be the requested resource (e.g., a list of users in JSON format). For an error, this might contain a message explaining what went wrong.

🛠️ The Request-Response Cycle in Python

When working with APIs in Python, you typically use the requests library. The cycle is straightforward:

Construct the Request: You define the method, URL, headers, and body.
Send the Request: You use a function like requests.get() or requests.post().
Receive the Response: The server returns a Response object.
Parse the Response: You extract the status code, headers, and body from the Response object.

For example, a simple GET request to fetch data would look like this in your code:

You define a variable for the URL: url = "https://api.example.com/users"
You send the request: response = requests.get(url)
You check the status: response.status_code (e.g., 200)
You access the data: response.json() (which parses the JSON body into a Python dictionary)

🕵️ Key Concepts for Engineers

Understanding these models helps you debug and build robust integrations:

Statelessness: Each request from a client to a server must contain all the information needed to understand and process the request. The server does not store any client context between requests.
Idempotency: Some methods (like GET, PUT, DELETE) are idempotent, meaning making the same request multiple times has the same effect as making it once. POST is not idempotent.
Resource-Based: Everything in REST is a resource (e.g., a user, an order, a file). URLs represent these resources, and HTTP methods define the operations on them.

📊 Comparison: Common HTTP Methods in the Request-Response Model

Method	Purpose	Request Body	Response Body	Idempotent
GET	Retrieve a resource	No	Yes (the resource)	Yes
POST	Create a new resource	Yes (new resource data)	Yes (the created resource)	No
PUT	Update/replace a resource	Yes (full resource data)	Yes (the updated resource)	Yes
PATCH	Partially update a resource	Yes (partial data)	Yes (the updated resource)	No
DELETE	Remove a resource	No	Usually empty (204)	Yes

✅ Summary

The REST API Request-Response Framework is a simple but powerful model. As an engineer, your primary tasks are to: - Construct the correct request (method, URL, headers, body). - Send it to the server. - Interpret the response (status code and body) to determine success or failure.

Mastering this cycle is the first step toward effectively consuming and building APIs. The requests library in Python makes this process clean and intuitive, allowing you to focus on the logic of your application rather than the low-level details of HTTP.

This guide shows how REST APIs use request-response models to let engineers send data and get structured replies.

🟢 Example 1: Simple GET request to fetch data

This example shows the most basic request-response model where an engineer asks for data and gets a list back.

import requests

response = requests.get("https://jsonplaceholder.typicode.com/posts/1")
print(response.status_code)
print(response.json())

📤 Output: 200 {'userId': 1, 'id': 1, 'title': 'sunt aut facere repellat provident occaecati excepturi optio reprehenderit', 'body': 'quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto'}

🟢 Example 2: POST request with a JSON body

This example shows how an engineer sends new data to a server and gets back the created resource with an ID.

import requests

new_post = {
    "title": "Python for Engineers",
    "body": "Learning REST APIs step by step",
    "userId": 1
}
response = requests.post("https://jsonplaceholder.typicode.com/posts", json=new_post)
print(response.status_code)
print(response.json())

📤 Output: 201 {'title': 'Python for Engineers', 'body': 'Learning REST APIs step by step', 'userId': 1, 'id': 101}

🟢 Example 3: PUT request to update an entire resource

This example shows how an engineer replaces all fields of an existing resource using a full update model.

import requests

updated_post = {
    "id": 1,
    "title": "Updated Title for Engineers",
    "body": "This replaces the entire post body",
    "userId": 1
}
response = requests.put("https://jsonplaceholder.typicode.com/posts/1", json=updated_post)
print(response.status_code)
print(response.json())

📤 Output: 200 {'id': 1, 'title': 'Updated Title for Engineers', 'body': 'This replaces the entire post body', 'userId': 1}

🟢 Example 4: PATCH request for partial updates

This example shows how an engineer sends only the fields that need changing, leaving the rest untouched.

import requests

partial_update = {
    "title": "Partially Updated Title"
}
response = requests.patch("https://jsonplaceholder.typicode.com/posts/1", json=partial_update)
print(response.status_code)
print(response.json())

📤 Output: 200 {'userId': 1, 'id': 1, 'title': 'Partially Updated Title', 'body': 'quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto'}

🟢 Example 5: DELETE request with status confirmation

This example shows how an engineer removes a resource and checks the response status to confirm deletion.

import requests

response = requests.delete("https://jsonplaceholder.typicode.com/posts/1")
print(response.status_code)
if response.status_code == 200:
    print("Resource deleted successfully")
else:
    print("Deletion failed")

📤 Output: 200 Resource deleted successfully

📊 Request-Response Model Comparison

HTTP Method	Purpose	Body Required	Typical Status Code
GET	Fetch data	No	200 OK
POST	Create new resource	Yes	201 Created
PUT	Replace entire resource	Yes	200 OK
PATCH	Partial update	Yes	200 OK
DELETE	Remove resource	No	200 OK or 204 No Content