Python Requests Library Explained — HTTP, APIs and Real-World Patterns

import requests

# The GitHub API is public and requires no auth for basic profile lookups
GITHUB_API_URL = "https://api.github.com/users/torvalds"

# Make the GET request — Requests handles the TCP connection, HTTP headers, and response parsing
response = requests.get(GITHUB_API_URL)

# Always check if the request succeeded before using the data
# raise_for_status() raises an HTTPError for 4xx and 5xx responses
response.raise_for_status()

# Parse the JSON body into a Python dictionary automatically
user_profile = response.json()

# Extract and display meaningful fields
print(f"Name        : {user_profile['name']}")
print(f"Public Repos: {user_profile['public_repos']}")
print(f"Followers   : {user_profile['followers']}")
print(f"Profile URL : {user_profile['html_url']}")

# Show the HTTP status code and the Content-Type header from the response
print(f"\nStatus Code : {response.status_code}")
print(f"Content-Type: {response.headers['Content-Type']}")

import requests
import os

# Load the token from an environment variable — never hardcode secrets in source code
github_token = os.environ.get("GITHUB_TOKEN")

if not github_token:
    raise EnvironmentError("GITHUB_TOKEN environment variable is not set.")

# Target repo for creating the issue
REPO_OWNER = "your-username"
REPO_NAME  = "your-test-repo"
API_URL    = f"https://api.github.com/repos/{REPO_OWNER}/{REPO_NAME}/issues"

# The payload we're sending — Requests will serialise this dict to JSON automatically
issue_payload = {
    "title": "Bug: Login page crashes on empty password field",
    "body": "Steps to reproduce:\n1. Navigate to /login\n2. Leave password blank\n3. Click Submit\n\nExpected: Validation error\nActual: 500 Internal Server Error",
    "labels": ["bug", "high-priority"]
}

# Authorization header — Bearer token is the GitHub API standard
request_headers = {
    "Authorization": f"Bearer {github_token}",
    "Accept": "application/vnd.github+json",
    "X-GitHub-Api-Version": "2022-11-28"
}

# Using json= automatically sets Content-Type to application/json
response = requests.post(
    url=API_URL,
    json=issue_payload,       # NOT data= — that would send form-encoded data
    headers=request_headers
)

# 201 Created is the expected success code for resource creation
response.raise_for_status()

created_issue = response.json()
print(f"Issue #{created_issue['number']} created successfully.")
print(f"Title : {created_issue['title']}")
print(f"URL   : {created_issue['html_url']}")

# Also demonstrate query params — search issues with ?state=open
search_url = f"https://api.github.com/repos/{REPO_OWNER}/{REPO_NAME}/issues"
search_params = {"state": "open", "per_page": 5}

open_issues_response = requests.get(
    url=search_url,
    params=search_params,     # Requests builds the URL: ...?state=open&per_page=5
    headers=request_headers
)
open_issues_response.raise_for_status()

print(f"\nOpen issues returned: {len(open_issues_response.json())}")

import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
import os

def build_resilient_session(base_url: str, api_token: str) -> requests.Session:
    """
    Creates a reusable session with:
    - Shared auth headers (set once, used everywhere)
    - Automatic retries on transient failures
    - A base URL so callers only pass the path
    """
    session = requests.Session()

    # These headers are sent with EVERY request made through this session
    session.headers.update({
        "Authorization": f"Bearer {api_token}",
        "Accept": "application/json",
        "User-Agent": "TheCodeForge-Demo/1.0"
    })

    # Retry strategy: retry up to 3 times on these specific status codes
    # backoff_factor=1 means wait 1s, then 2s, then 4s between retries
    retry_strategy = Retry(
        total=3,
        backoff_factor=1,
        status_forcelist=[429, 500, 502, 503, 504],  # Common transient failures
        allowed_methods=["GET", "POST"]               # Only retry safe or idempotent methods
    )

    # Mount the retry adapter for both HTTP and HTTPS traffic
    http_adapter = HTTPAdapter(max_retries=retry_strategy)
    session.mount("https://", http_adapter)
    session.mount("http://",  http_adapter)

    return session


# --- Usage Example ---
api_token = os.environ.get("WEATHER_API_KEY", "demo_key")
BASE_URL  = "https://api.open-meteo.com/v1"

session = build_resilient_session(base_url=BASE_URL, api_token=api_token)

try:
    # timeout=(3, 10): wait 3s to connect, wait 10s to receive data
    # If either limit is exceeded, a Timeout exception is raised — not a silent hang
    response = session.get(
        url=f"{BASE_URL}/forecast",
        params={
            "latitude": 51.5074,   # London
            "longitude": -0.1278,
            "current_weather": True
        },
        timeout=(3, 10)            # ALWAYS set a timeout in production code
    )
    response.raise_for_status()

    weather_data = response.json()
    current      = weather_data["current_weather"]

    print(f"Temperature : {current['temperature']} °C")
    print(f"Wind Speed  : {current['windspeed']} km/h")
    print(f"Weather Code: {current['weathercode']}")

except requests.exceptions.Timeout:
    print("ERROR: The API took too long to respond. Try again later.")
except requests.exceptions.ConnectionError:
    print("ERROR: Could not connect. Check your internet connection.")
except requests.exceptions.HTTPError as http_err:
    print(f"ERROR: HTTP error occurred — {http_err}")
finally:
    # Always close the session to release the underlying socket connection
    session.close()

import requests
from requests.auth import HTTPBasicAuth, HTTPDigestAuth
import os

# ─── PATTERN 1: Basic Auth ───────────────────────────────────────────────────
# Requests encodes "username:password" as Base64 and sets the Authorization header
# Only use over HTTPS — never HTTP

basic_response = requests.get(
    url="https://httpbin.org/basic-auth/demo_user/secret123",
    auth=HTTPBasicAuth("demo_user", "secret123"),  # Tuple shorthand also works: auth=("demo_user", "secret123")
    timeout=(3, 10)
)
basic_response.raise_for_status()
print("Basic Auth Result:", basic_response.json())


# ─── PATTERN 2: Bearer Token Auth ────────────────────────────────────────────
# The most common pattern for modern REST APIs
# Token is obtained once (login, API key dashboard) and reused

api_token = os.environ.get("MY_API_TOKEN", "mock_token_abc123")

token_session = requests.Session()
token_session.headers.update({
    "Authorization": f"Bearer {api_token}",
    "Content-Type": "application/json"
})

# Every request through token_session automatically includes the auth header
token_response = token_session.get(
    url="https://httpbin.org/bearer",
    timeout=(3, 10)
)
token_response.raise_for_status()
print("\nBearer Token Result:", token_response.json())
token_session.close()


# ─── PATTERN 3: API Key as Header (common with services like OpenAI, Stripe) ──
# Some APIs use a custom header name instead of the standard Authorization header

api_key = os.environ.get("SERVICE_API_KEY", "sk-demo-key-9999")

header_key_response = requests.get(
    url="https://httpbin.org/headers",
    headers={
        "X-API-Key": api_key,       # Custom header name — check your API's docs
        "Accept": "application/json"
    },
    timeout=(3, 10)
)
header_key_response.raise_for_status()

returned_headers = header_key_response.json()["headers"]
print(f"\nAPI Key sent as header: {returned_headers.get('X-Api-Key', 'not found')}")