Python HTTP & REST API Guide
An API (Application Programming Interface) is a standardized communication contract that allows two independent software systems to exchange data over a network, regardless of the programming language or operating system each system is written in.
The REST (Representational State Transfer) Paradigm:
REST is an architectural style designed by Roy Fielding in 2000 that governs how web services communicate over HTTP:
- Client-Server Separation: The user interface (React, mobile app) and the data storage backend (Python FastAPI/Django) operate independently.
- Statelessness: The server does not remember previous requests. Every single HTTP request from the client must carry all required authentication tokens and context.
- Resource-Oriented URIs: Resources are represented by clear nouns, not verbs:
GET /api/v1/users(Fetch all users)POST /api/v1/users(Create a user)GET /api/v1/users/42(Fetch user with ID 42)DELETE /api/v1/users/42(Delete user with ID 42)
# Exploring HTTP Status Code Meanings and Classifications:
status_code_dictionary = {
200: ("OK", "Standard success response for GET, PUT, PATCH requests"),
201: ("Created", "Resource successfully created on server (POST response)"),
204: ("No Content", "Action succeeded, response body is intentionally empty (DELETE)"),
400: ("Bad Request", "Malformed payload or missing required request fields"),
401: ("Unauthorized", "Missing or invalid authentication token/credentials"),
403: ("Forbidden", "Authenticated user lacks permissions to access this resource"),
404: ("Not Found", "Target resource endpoint or ID does not exist on server"),
429: ("Too Many Requests", "Client exceeded API rate limit ceiling"),
500: ("Internal Server Error", "Unhandled exception or crash on remote server"),
503: ("Service Unavailable", "Server is down for maintenance or overloaded")
}
print("--- 🌐 Core HTTP Status Code Reference ---")
for code, (label, meaning) in status_code_dictionary.items():
emoji = "✅" if code < 300 else ("⚠️" if code < 500 else "🔥")
print(f"{emoji} HTTP {code} [{label:20}]: {meaning}")A well-designed REST API always returns the appropriate HTTP status code. Returning HTTP 200 with an error body {"error": "User not found"} is an anti-pattern; it should return HTTP 404 Not Found.
In Python, the requests library is the industry standard tool for HTTP communication. It abstracts low-level socket programming into clean, intuitive methods:
requests.get(url, params={...}): Queries data and attaches URL query parameters.requests.post(url, json={...}): Serializes a dictionary to JSON and sends it in the HTTP request body.requests.put(url, json={...}): Replaces an entire existing resource.requests.patch(url, json={...}): Partially updates specific fields on a resource.requests.delete(url): Removes the resource from the server.
import json
# Comprehensive REST Client Architecture Simulation:
class SimulatedRESTClient:
"""Demonstrates complete HTTP REST CRUD operations."""
def __init__(self, base_url="https://api.example.com/v1"):
self.base_url = base_url
def get_user_profile(self, user_id):
endpoint = f"{self.base_url}/users/{user_id}"
print(f"👉 [GET] Requesting: {endpoint}")
# Simulated successful 200 OK response:
return {"status_code": 200, "data": {"id": user_id, "name": "Balaji", "role": "Engineer"}}
def create_user(self, payload):
endpoint = f"{self.base_url}/users"
print(f"👉 [POST] Creating resource at {endpoint} with payload: {json.dumps(payload)}")
# Simulated 201 Created response:
return {"status_code": 201, "data": {"id": 105, **payload, "created_at": "2026-08-14"}}
def update_user_email(self, user_id, new_email):
endpoint = f"{self.base_url}/users/{user_id}"
print(f"👉 [PATCH] Partially updating {endpoint}: {{'email': '{new_email}'}}")
return {"status_code": 200, "data": {"id": user_id, "email": new_email, "updated": True}}
def delete_user(self, user_id):
endpoint = f"{self.base_url}/users/{user_id}"
print(f"👉 [DELETE] Deleting resource: {endpoint}")
return {"status_code": 204, "data": None}
# Execute Full CRUD Lifecycle:
client = SimulatedRESTClient()
print("1. GET Request:")
print(" Response:", client.get_user_profile(42))
print("\n2. POST Request (Create):")
print(" Response:", client.create_user({"name": "Chloe Davis", "email": "chloe@example.com"}))
print("\n3. PATCH Request (Partial Update):")
print(" Response:", client.update_user_email(42, "balaji.updated@example.com"))
print("\n4. DELETE Request:")
print(" Response:", client.delete_user(42))PUT replaces the entire record (if you omit a field, that field becomes null). PATCH modifies only the fields you explicitly specify in the payload, leaving all other existing properties untouched.
While json.loads(response.text) works, response.json() is built directly into requests. It uses the server's HTTP header charset to decode the body automatically before JSON parsing, preventing character encoding bugs.
Build a Python function parse_api_response(status, raw_json_str) that returns (True, data) if status is 200/201, or (False, error_message) for 4xx/5xx.
import json
def parse_api_response(status_code, raw_body_str):
try:
data = json.loads(raw_body_str)
if 200 <= status_code < 300:
return True, data
return False, f"Server returned error code {status_code}: {data.get('error', 'Unknown Error')}"
except json.JSONDecodeError:
return False, "Failed to parse invalid JSON from server response"
success, res = parse_api_response(200, '{"user": "Balaji", "status": "active"}')
print(f"Status 200: Success={success}, Data={res}")
success_err, res_err = parse_api_response(404, '{"error": "User ID 999 not found"}')
print(f"Status 404: Success={success_err}, Error={res_err}")Q What is CORS (Cross-Origin Resource Sharing)?
CORS is a browser security mechanism that restricts web pages from making HTTP requests to a different domain/port than the one that served the page, unless the backend server includes appropriate "Access-Control-Allow-Origin" headers.
Q What is the difference between JSON and Python Dictionaries?
A Python dictionary is an in-memory runtime data structure with native Python types. JSON (JavaScript Object Notation) is a standardized text format used for data interchange over networks. Python uses json.dumps() to serialize dictionaries to JSON strings, and json.loads() to deserialize.
Q What is a webhook in API development?
A webhook is a "reverse API" where the server proactively sends an HTTP POST request to your application URL when an event occurs (e.g. Stripe sending a webhook when a payment succeeds), eliminating the need for periodic polling.