Python REST APIs

Learning Objectives

REST APIs are one of the most common ways applications exchange information over the internet. By the end of this lesson, you will understand how REST APIs are designed and how Python applications consume them.

What Is an API?

API stands for Application Programming Interface.

An API provides a defined way for one software system to communicate with another software system.

For example, an ecommerce application might communicate with a payment service through an API.

Ecommerce Website
       ↓
   API Request
       ↓
Payment Service
       ↓
   API Response
       ↓
Ecommerce Website

What Is REST?

REST stands for Representational State Transfer.

REST is an architectural style for designing networked applications. REST APIs commonly use HTTP and represent information as resources.

A RESTful API generally uses:

• HTTP methods
• Resource-based URLs
• Stateless requests
• Standard HTTP status codes
• Representations such as JSON

REST Resources

REST APIs commonly organize data around resources.

In an ecommerce application, resources might include:

/products
/customers
/orders
/categories
/reviews

A particular product could be represented as:

/products/101

Here, 101 identifies a specific product.

HTTP Methods

REST APIs use HTTP methods to communicate the intended operation.

GET     /products
POST    /products
GET     /products/101
PUT     /products/101
PATCH   /products/101
DELETE  /products/101

API URLs and Endpoints

An API endpoint is a specific URL through which a client interacts with a resource.

https://api.example.com/products

A versioned API might look like:

https://api.example.com/v1/products

A specific resource might be:

https://api.example.com/v1/products/25

JSON Data

REST APIs frequently use JSON to represent structured data.

{
    "id": 101,
    "name": "Laptop",
    "price": 1200,
    "stock": 15
}

Python can convert JSON responses into dictionaries and lists.

import requests

response = requests.get(
    "https://example.com/api/products"
)

data = response.json()

print(data["name"])

A JSON array may become a Python list.

[
    {
        "id": 1,
        "name": "Laptop"
    },
    {
        "id": 2,
        "name": "Phone"
    }
]

GET Requests

GET is commonly used to retrieve resources.

import requests

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

response = requests.get(
    url,
    timeout=10
)

response.raise_for_status()

products = response.json()

for product in products:
    print(product["name"])

This pattern is common when consuming an API:

Request
   ↓
Status Check
   ↓
JSON Parsing
   ↓
Python Data
   ↓
Application Logic

POST Requests

POST is commonly used to create a new resource.

import requests

product = {
    "name": "Laptop",
    "price": 1200,
    "stock": 10
}

response = requests.post(
    "https://example.com/api/products",
    json=product,
    timeout=10
)

print(response.status_code)

A successful resource creation commonly results in status code 201 Created.

PUT Requests

PUT is commonly associated with replacing an existing resource with a new representation.

import requests

updated_product = {
    "name": "Laptop Pro",
    "price": 1500,
    "stock": 20
}

response = requests.put(
    "https://example.com/api/products/101",
    json=updated_product,
    timeout=10
)

print(response.status_code)

The exact behavior depends on the API implementation.

PATCH Requests

PATCH is generally used when only part of a resource needs to be changed.

import requests

changes = {
    "price": 1400
}

response = requests.patch(
    "https://example.com/api/products/101",
    json=changes,
    timeout=10
)

print(response.status_code)

DELETE Requests

DELETE is commonly used to remove a resource.

import requests

response = requests.delete(
    "https://example.com/api/products/101",
    timeout=10
)

print(response.status_code)

Some APIs return 204 No Content after a successful deletion.

HTTP Status Codes

Status codes allow your application to determine what happened during an API request.

Request Headers

Headers provide additional information about a request.

import requests

headers = {
    "Accept": "application/json",
    "User-Agent": "PyLearn-App"
}

response = requests.get(
    "https://example.com/api/products",
    headers=headers,
    timeout=10
)

print(response.status_code)

APIs may use headers to communicate content formats, authentication credentials and other metadata.

API Authentication

Public APIs may allow anonymous requests, while private APIs usually require authentication.

One common authentication pattern is a bearer token.

import requests

token = "YOUR_API_TOKEN"

headers = {
    "Authorization": f"Bearer {token}"
}

response = requests.get(
    "https://example.com/api/profile",
    headers=headers,
    timeout=10
)

response.raise_for_status()

print(response.json())

A better approach is to read secrets from environment variables or a dedicated secrets-management system.

Pagination

APIs may contain thousands or millions of records. Returning everything in one response would be inefficient.

APIs therefore commonly divide results into pages.

GET /products?page=1
GET /products?page=2
GET /products?page=3

A Python client might request multiple pages:

import requests

all_products = []

for page in range(1, 4):

    response = requests.get(
        "https://example.com/api/products",
        params={"page": page},
        timeout=10
    )

    response.raise_for_status()

    products = response.json()

    all_products.extend(products)

print("Products:", len(all_products))

Filtering & Searching

APIs often provide query parameters that allow clients to request only the data they need.

params = {
    "category": "electronics",
    "min_price": 500,
    "page": 1
}

response = requests.get(
    "https://example.com/api/products",
    params=params,
    timeout=10
)

Search parameters might look like:

GET /products?search=laptop
GET /products?category=electronics
GET /products?sort=price

The exact parameter names are determined by the API.

Handling API Errors

A professional API client should expect failures.

import requests

try:

    response = requests.get(
        "https://example.com/api/products",
        timeout=10
    )

    response.raise_for_status()

    data = response.json()

except requests.exceptions.Timeout:

    print("The request timed out.")

except requests.exceptions.HTTPError as error:

    print("HTTP error:", error)

except requests.exceptions.ConnectionError:

    print("Could not connect to the server.")

except ValueError:

    print("The response was not valid JSON.")

except requests.exceptions.RequestException as error:

    print("Request failed:", error)

Building a Reusable API Client

Instead of repeating the same request logic throughout your program, you can create functions or classes that act as an API client.

import requests


def get_products(base_url):

    response = requests.get(
        f"{base_url}/products",
        timeout=10
    )

    response.raise_for_status()

    return response.json()


products = get_products(
    "https://example.com/api"
)

for product in products:
    print(product["name"])

This separates network communication from the rest of your application logic.

Practical Ecommerce Example

Imagine that an ecommerce application receives product information from an external API.

import requests


def fetch_products():

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

    try:

        response = requests.get(
            url,
            params={
                "category": "electronics",
                "page": 1
            },
            timeout=10
        )

        response.raise_for_status()

        return response.json()

    except requests.exceptions.RequestException as error:

        print("API request failed:", error)

        return []


products = fetch_products()

for product in products:

    name = product.get("name", "Unknown")
    price = product.get("price", 0)

    print(f"{name}: ${price}")

This example demonstrates several professional concepts together:

• Function abstraction
• Query parameters
• Timeouts
• HTTP error handling
• JSON parsing
• Safe dictionary access

REST API Best Practices

1. Use Timeouts

Never assume that a remote server will respond immediately.

2. Check Status Codes

Always determine whether the operation succeeded.

3. Handle Exceptions

Network failures are normal possibilities and should be handled.

4. Protect Credentials

Keep API keys and tokens outside public source code.

5. Respect Rate Limits

APIs may limit how many requests a client can make.

6. Read API Documentation

Never guess an API's endpoints, parameters or required fields when documentation is available.

7. Keep API Logic Organized

Put repeated API communication into reusable functions or classes.

Common REST API Mistakes

Practice Exercises

Mini Challenge — Ecommerce REST API Client

Build a small Python API client for an imaginary ecommerce platform.

Starter Code

import requests


def get_products(page=1):

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

    try:

        response = requests.get(
            url,
            params={
                "page": page
            },
            timeout=10
        )

        response.raise_for_status()

        return response.json()

    except requests.exceptions.RequestException as error:

        print("API error:", error)

        return []


products = get_products(page=1)

for product in products:

    name = product.get("name", "Unknown")
    price = product.get("price", 0)

    if price > 500:
        print(
            f"{name} - ${price}"
        )

Advanced Extension

Extend your program so that it:

• retrieves multiple pages,
• counts the total products,
• calculates the average price,
• finds the most expensive product,
• stores the results in SQLite.

REST API
    ↓
Requests
    ↓
JSON
    ↓
Python Data
    ↓
Data Processing
    ↓
SQLite
    ↓
Ecommerce Report

Knowledge Check

Lesson Summary

REST APIs provide a structured way for applications to communicate over HTTP.

You now understand the architecture behind many modern web services. In the next lesson, we will move from consuming APIs to another powerful Python skill: Web Scraping.