Pagination is a common requirement when building APIs, especially when dealing with large datasets. It helps improve performance and user experience by returning only a subset of data at a time. FastAPI makes it easy to implement pagination in your applications. In this guide, we will cover the fundamentals of pagination and provide you with a practical example.

What is Pagination?

Pagination is the process of dividing a large set of data into smaller, more manageable sections, called "pages." This allows clients to request only a specific subset of data, rather than fetching all records at once, which can be inefficient and slow.

Basic Concept of Pagination

Typically, pagination involves the following parameters:

• page: The current page number.
• size: The number of items per page.

Setting Up FastAPI

If you haven't already, you need to install FastAPI and an ASGI server like Uvicorn. You can do this via pip:

pip install fastapi uvicorn

Now let’s create a basic FastAPI application where we will implement pagination.

Example: Implementing Pagination

Step 1: Create Sample Data

First, we'll set up some sample data to work with. For simplicity, we’ll use a list of dictionaries.

from fastapi import FastAPI
from typing import List

app = FastAPI()

# Sample data
fake_items = [{"item_id": i, "item_name": f"Item {i}"} for i in range(1, 101)]

# 100 items

Step 2: Create a Pagination Endpoint

Next, we’ll create an endpoint that allows us to fetch a paginated list of items.

@app.get("/items/", response_model=List[dict])
def read_items(page: int = 1, size: int = 10):
    start = (page - 1) * size
    end = start + size
    return fake_items[start:end]

Explanation:

• The read_items function takes two query parameters: page and size.
• The start index is calculated by multiplying (page - 1) by the size. This gives us the starting index of the items for the requested page.
• The end index is simply the start index plus the size.
• Finally, we return a slice of the fake_items list based on the calculated indices.

Step 3: Test the Pagination

To test the pagination, run your FastAPI application using Uvicorn:

uvicorn main:app --reload

You can then access the endpoint in your browser or with a tool like cURL or Postman:

• Get the first page with 10 items:

  GET http://127.0.0.1:8000/items/?page=1&size=10
  

• Get the second page with 5 items:

  GET http://127.0.0.1:8000/items/?page=2&size=5
  

Step 4: Adding Validation and Default Values

For a more robust implementation, it’s a good idea to add validation and set default values for the pagination parameters. Here’s how you can do that:

from fastapi import HTTPException

@app.get("/items/", response_model=List[dict])
def read_items(page: int = 1, size: int = 10):
    if page < 1 or size < 1:
        raise HTTPException(status_code=400, detail="Page and size must be greater than 0.")
    start = (page - 1) * size
    end = start + size
    return fake_items[start:end]

Conclusion

Through this guide, you’ve learned how to implement basic pagination in a FastAPI application. You can expand on this by adding features like total item count, next/previous page links, and more sophisticated data models. This approach will help you enhance the performance and user experience of your APIs. Happy coding!