How to Implement Sorting in FastAPI: Simple Guide

To implement sorting in FastAPI, accept a query parameter that specifies the sort field and direction, then use Python's sorted() function or list methods to order your data accordingly before returning it. This approach lets clients control sorting dynamically via URL parameters.

Syntax

Use query parameters in your FastAPI endpoint to receive sorting instructions. Typically, you define a parameter like sort_by for the field name and order for ascending or descending order.

Inside the endpoint, apply Python's sorted() function with a key argument to sort your data list. Use reverse=True for descending order.

python

from fastapi import FastAPI, Query
from typing import List

app = FastAPI()

items = [
    {"name": "apple", "price": 5},
    {"name": "banana", "price": 3},
    {"name": "cherry", "price": 7}
]

@app.get("/items")
async def get_items(sort_by: str = Query("name"), order: str = Query("asc")):
    reverse = order == "desc"
    sorted_items = sorted(items, key=lambda x: x.get(sort_by), reverse=reverse)
    return sorted_items

Example

This example shows a FastAPI endpoint /items that returns a list of fruit items sorted by the field and order specified in the query parameters. You can call /items?sort_by=price&order=desc to get items sorted by price from highest to lowest.

python

from fastapi import FastAPI, Query
from typing import List

app = FastAPI()

items = [
    {"name": "apple", "price": 5},
    {"name": "banana", "price": 3},
    {"name": "cherry", "price": 7}
]

@app.get("/items")
async def get_items(sort_by: str = Query("name"), order: str = Query("asc")):
    reverse = order == "desc"
    sorted_items = sorted(items, key=lambda x: x.get(sort_by), reverse=reverse)
    return sorted_items

Output

[{"name": "cherry", "price": 7}, {"name": "apple", "price": 5}, {"name": "banana", "price": 3}]

Common Pitfalls

• Not validating the sort_by parameter can cause errors if the field does not exist in data.
• Ignoring the order parameter or using incorrect values can lead to unexpected sorting results.
• Sorting large datasets in memory can be inefficient; consider database-level sorting for big data.

python

from fastapi import FastAPI, Query, HTTPException

app = FastAPI()

items = [
    {"name": "apple", "price": 5},
    {"name": "banana", "price": 3},
    {"name": "cherry", "price": 7}
]

valid_sort_fields = {"name", "price"}

@app.get("/items")
async def get_items(sort_by: str = Query("name"), order: str = Query("asc")):
    if sort_by not in valid_sort_fields:
        raise HTTPException(status_code=400, detail="Invalid sort field")
    if order not in {"asc", "desc"}:
        raise HTTPException(status_code=400, detail="Invalid order value")
    reverse = order == "desc"
    sorted_items = sorted(items, key=lambda x: x.get(sort_by), reverse=reverse)
    return sorted_items

Quick Reference

Concept	Description	Example
Query Parameter	Defines sorting field and order	sort_by=name&order=desc
sorted() Function	Sorts list by key with optional reverse	sorted(items, key=lambda x: x['price'], reverse=True)
Validation	Check if sort field and order are valid	Raise 400 error if invalid
Reverse Sorting	Use reverse=True for descending	Set reverse = (order == 'desc')

Key Takeaways

Use query parameters to let clients specify sorting field and order in FastAPI.

Apply Python's sorted() with a key function and reverse flag to sort data.

Always validate sorting parameters to avoid errors and unexpected behavior.

For large datasets, prefer database sorting over in-memory sorting for performance.

Clear error messages improve API usability when invalid sorting parameters are given.