APIs & HTTP

Modern applications rarely work alone — a weather app needs real weather data from somewhere, a payment page needs to talk to a bank, a chat app needs to send messages to a server. APIs are how different programs communicate with each other over the internet, and HTTP is the language they use to do it.

1. What is HTTP?

What is it?

HTTP (HyperText Transfer Protocol) is the standard set of rules that defines how computers request and send data over the internet.

Definition: HTTP is a protocol that defines how requests and responses are exchanged between a client and a server over the web.

The Client-Server Model

• The client is the one requesting something — your browser, your phone app, or a Python script.
• The server is the one that has the data or service and responds to requests.

How does it work?

1. The client sends a request to a server (e.g., "give me the weather for Mumbai").
2. The server processes the request and sends back a response (e.g., the actual weather data).

This request-response pattern is the foundation of essentially the entire internet.

Real-World Example

When you open a weather app, it sends a request to a weather API (a server that provides weather data), which responds with the current temperature and forecast — all within a second or two.

2. What is an API?

What is it?

An API (Application Programming Interface) is a defined way for one piece of software to communicate with another. A web API specifically allows communication over HTTP, usually exchanging data in JSON format.

Definition: An API is a set of rules that allows different software applications to communicate with each other.

Why do we use it?

• To use data or services someone else has already built (weather, maps, payments) instead of building it all yourself.
• To let your own application's frontend (a mobile app or website) talk to your backend server.
• To connect different systems together (e.g., an e-commerce site talking to a shipping company's tracking system).

3. HTTP Methods

What is it?

HTTP methods describe the type of action a request wants to perform.

Simple Example — Conceptual

GET /students/5          → Fetch student with ID 5
POST /students            → Create a new student
PUT /students/5           → Replace ALL data for student 5
PATCH /students/5         → Update just one field for student 5
DELETE /students/5        → Delete student 5

Common Mistakes

• Using GET for operations that change data — GET requests should be safe to repeat without side effects (this is called being "idempotent" for reads).
• Confusing PUT (replaces the entire resource) with PATCH (updates only specific fields).

Important Points

• GET and DELETE typically don't send a body of data; POST, PUT, and PATCH typically do.
• These methods form the backbone of REST APIs (explained below).

4. Headers

What is it?

Headers are extra pieces of metadata sent along with an HTTP request or response — information about the request, separate from the actual data (the "body").

Common Headers

Simple Example

python
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY_HERE"
}

Important Points

• Headers are essential for authentication and specifying data formats.
• Authorization: Bearer <token> is an extremely common pattern for API authentication.

5. Status Codes

What is it?

A status code is a 3-digit number in every HTTP response, indicating whether the request succeeded, and if not, roughly why.

Status Code Ranges

Most Common Status Codes

Common Mistakes

• Assuming any response means success — always check the status code before trusting the response data.
• Confusing 401 (not authenticated at all) with 403 (authenticated, but not permitted to access this specific thing).

Important Points

• 2xx = success, 4xx = your request's fault, 5xx = the server's fault.
• Checking status codes is essential for reliable API integration.

6. JSON in APIs

Quick Recap

APIs almost universally exchange data as JSON — a lightweight, text-based format representing structured data (covered in depth in the File Handling file). A typical API response looks like this:

json
{
    "city": "Mumbai",
    "temperature": 31,
    "condition": "Sunny",
    "humidity": 65
}

Python's requests library (below) automatically converts this into a Python dictionary for you.

7. REST — Representational State Transfer

What is it?

REST is a widely adopted architectural style for designing APIs — a set of conventions (not a strict technology) about how to organize URLs and HTTP methods so APIs are predictable and consistent.

Simple Example — RESTful URL Design

GET    /students          → get all students
GET    /students/5        → get student with ID 5
POST   /students          → create a new student
PUT    /students/5        → replace student 5's data
DELETE /students/5        → delete student 5

Important Points

• REST APIs organize data around resources (like /students, /products), acted on using standard HTTP methods.
• Most public APIs you'll use as a developer (weather, maps, payment gateways) follow REST conventions.

8. Authentication

What is it?

Most real-world APIs require you to prove who you are before granting access — this is authentication.

Common Authentication Methods

API Key (very common for simple public APIs):

python
url = "https://api.example.com/weather"
params = {"apikey": "YOUR_API_KEY", "city": "Mumbai"}

Bearer Token (common for modern APIs, including OAuth-based ones):

python
headers = {"Authorization": "Bearer YOUR_ACCESS_TOKEN"}

Basic Auth (username/password, less common today):

python
from requests.auth import HTTPBasicAuth
response = requests.get(url, auth=HTTPBasicAuth("username", "password"))

Common Mistakes

• Hardcoding API keys directly in shared or public code (like a GitHub repository) — this is a serious security risk covered further in the Security file. Use environment variables instead.
• Forgetting that some APIs expect the key in the URL/params, others in headers — always check the specific API's documentation.

9. The requests Library

What is it?

requests is the most popular third-party Python library for making HTTP requests — far simpler to use than Python's built-in alternatives.

bash
pip install requests

Simple GET Request

python
import requests

response = requests.get("https://api.github.com/users/octocat")

print(response.status_code)   # 200
data = response.json()         # convert JSON response to a Python dictionary
print(data["login"])           # octocat
print(data["public_repos"])

GET Request With Query Parameters

python
import requests

url = "https://api.example.com/weather"
params = {"city": "Mumbai", "units": "metric"}

response = requests.get(url, params=params)
print(response.url)   # shows the full URL with parameters attached

POST Request — Sending Data

python
import requests

url = "https://api.example.com/students"
data = {"name": "Aditi", "age": 21, "course": "Computer Science"}

response = requests.post(url, json=data)
print(response.status_code)   # 201, if successfully created
print(response.json())

PUT, PATCH, and DELETE

python
requests.put(url, json={"name": "Aditi Updated"})     # replace entire resource
requests.patch(url, json={"age": 22})                  # update just one field
requests.delete(url)                                    # delete the resource

Explanation of the Code

• requests.get(), .post(), .put(), .patch(), .delete() map directly to their corresponding HTTP methods.
• json=data automatically converts a Python dictionary into a JSON body and sets the correct Content-Type header.
• .json() on the response automatically parses the server's JSON response back into a Python dictionary.

Practice

1. Use requests.get() on a free public API (like https://api.github.com/users/<any-username>) and print two pieces of information from the response.

10. Error Handling with APIs

What is it?

Real-world API calls can fail for many reasons: no internet connection, invalid credentials, the server being down. Robust code should handle these gracefully rather than crashing.

Simple Example

python
import requests

url = "https://api.example.com/weather"

try:
    response = requests.get(url, timeout=5)
    response.raise_for_status()   # raises an exception for 4xx/5xx status codes
    data = response.json()
    print(data)
except requests.exceptions.Timeout:
    print("The request took too long and timed out.")
except requests.exceptions.ConnectionError:
    print("Could not connect. Check your internet connection.")
except requests.exceptions.HTTPError as e:
    print(f"HTTP error occurred: {e}")
except requests.exceptions.RequestException as e:
    print(f"An unexpected error occurred: {e}")

Explanation of the Code

• timeout=5 ensures the program doesn't hang forever waiting for a slow or unresponsive server.
• response.raise_for_status() automatically raises an exception if the status code indicates an error (4xx or 5xx), which the following except blocks then catch and handle specifically.
• Catching specific exception types (Timeout, ConnectionError, HTTPError) lets you respond differently to each kind of failure.

Common Mistakes

• Not setting a timeout, which can cause a program to hang indefinitely if a server never responds.
• Assuming requests.get() always succeeds — always check the status code or use raise_for_status().
• Not handling connection errors when internet connectivity is unreliable.

Important Points

• Always wrap real-world API calls in try/except, and always set a timeout.
• response.raise_for_status() is a clean, standard way to detect failed requests.

Comparison Table — HTTP Methods at a Glance

(Idempotent means repeating the same request produces the same end result, without unwanted side effects.)

Common Beginner Mistakes — Summary for This Section

• Not checking the status code before trusting a response's data.
• Forgetting timeout on requests, risking the program hanging forever.
• Hardcoding API keys directly in code.
• Confusing PUT (whole resource replacement) with PATCH (partial update).
• Not wrapping API calls in proper exception handling.

Cheat Sheet — APIs & HTTP

python
import requests

requests.get(url, params={...}, headers={...}, timeout=5)
requests.post(url, json={...})
requests.put(url, json={...})
requests.patch(url, json={...})
requests.delete(url)

response.status_code
response.json()
response.text
response.raise_for_status()

Mini Project: Weather API Application

Objective

Build a command-line application that fetches and displays real-time weather data for any city, using a public weather API.

Requirements

• Ask the user for a city name.
• Call a weather API and retrieve the current temperature and conditions.
• Handle errors gracefully (invalid city, network issues).

(Note: this example uses a placeholder API structure. In practice, you would sign up for a free API key from a service like OpenWeatherMap and follow their specific documentation.)

Concepts Used

requests library, JSON parsing, exception handling, functions.

Complete Code

python
import requests

API_KEY = "YOUR_API_KEY_HERE"   # replace with a real API key
BASE_URL = "https://api.openweathermap.org/data/2.5/weather"

def get_weather(city):
    params = {
        "q": city,
        "appid": API_KEY,
        "units": "metric"
    }

    try:
        response = requests.get(BASE_URL, params=params, timeout=5)
        response.raise_for_status()
        data = response.json()

        temperature = data["main"]["temp"]
        condition = data["weather"][0]["description"]
        humidity = data["main"]["humidity"]

        print(f"\nWeather in {city}:")
        print(f"Temperature: {temperature}°C")
        print(f"Condition: {condition}")
        print(f"Humidity: {humidity}%")

    except requests.exceptions.HTTPError:
        print(f"Could not find weather data for '{city}'. Check the city name.")
    except requests.exceptions.ConnectionError:
        print("Connection error. Please check your internet connection.")
    except requests.exceptions.Timeout:
        print("The request timed out. Please try again.")


city_name = input("Enter a city name: ")
get_weather(city_name)

Code Explanation

• params builds the query string sent to the API (city name, API key, and unit preference).
• response.raise_for_status() catches issues like an invalid API key or an unrecognized city (which returns a 4xx status code).
• Specific except blocks handle different failure scenarios with clear, tailored messages instead of a generic crash.

Sample Output

Enter a city name: Mumbai

Weather in Mumbai:
Temperature: 31°C
Condition: clear sky
Humidity: 65%

Possible Improvements

• Add a 5-day forecast using the API's forecast endpoint.
• Let the user save favorite cities and check all of them at once.
• Add unit conversion (Celsius/Fahrenheit toggle).

Challenge Task

Extend the application to log every weather check (city, timestamp, temperature) to a CSV file, building a simple personal weather history log.

Interview Questions

Q1. What is the difference between `PUT` and `PATCH`? Answer: PUT replaces the entire resource with the new data provided. PATCH updates only the specific fields included in the request, leaving the rest unchanged.

Q2. What does a `404` status code mean? Answer: The requested resource could not be found on the server.

Q3. What is the difference between `401` and `403` status codes? Answer: 401 means the request lacks valid authentication credentials entirely. 403 means the client is authenticated, but doesn't have permission to access that specific resource.

Q4. Why is it important to set a `timeout` on API requests? Answer: Without a timeout, a request can hang indefinitely if the server is slow or unresponsive, potentially freezing the entire program.

Q5. What does `response.raise_for_status()` do? Answer: It automatically raises an HTTPError exception if the response's status code indicates a client (4xx) or server (5xx) error, making it easy to detect failed requests.

Q6. What is REST? Answer: An architectural style for designing APIs, organizing them around resources (URLs) that are acted upon using standard HTTP methods (GET, POST, PUT, DELETE, etc.), promoting consistency and predictability.

Practice Questions

Beginner

1. Make a GET request to a public API (e.g., a random joke API) and print the response.
2. Print the status code of a response and check whether it equals 200.
3. Send a GET request with query parameters to any public API of your choice.
4. Write code that catches a Timeout exception when making an API request.
5. Convert a Python dictionary to JSON and print it, then parse it back.

Intermediate

1. Write a function that takes a GitHub username and prints their number of public repositories using the GitHub API.
2. Write a program that fetches a list of posts from a public test API (like https://jsonplaceholder.typicode.com/posts) and prints the titles of the first 5.
3. Write a program that sends a POST request with a JSON body to a test API and prints the response.
4. Handle both ConnectionError and HTTPError separately in an API-calling function, with different messages for each.
5. Write a program that checks if a given username exists on GitHub by checking the response status code.

Challenge

1. Build a simple currency converter using a free exchange-rate API.
2. Extend the Weather API mini project to accept multiple cities at once and display a formatted comparison of their temperatures.
3. Write a program that fetches data from a paginated API (one that returns results across multiple "pages") and combines all pages into a single list.