Параметри запитів: робота з Query Parameters

Сьогодні ми копнемо трохи глибше і зануримося в світ Query Parameters (параметрів запиту). Це потужний інструмент, що дозволяє перетворити ваш API на швейцарський ніж. Усіма зручностями: сідайте поудобніше, готуйтеся до практики, і розбираємося.

Query Parameters — це параметри, які передаються в URL в межах HTTP-запитів. Ви напевно бачили їх у браузері, наприклад:

https://example.com/search?query=fastapi&page=2

Тут:

• query=fastapi — передає рядок для пошуку.
• page=2 — вказує, що користувач запитує другу сторінку результату.

Параметри запиту починаються після знака питання ? і йдуть у форматі ключ=значення. Декілька параметрів розділяються амперсандом &.

У FastAPI працювати з ними — одне задоволення. Так-так, серйозно!

---

Як отримувати Query Parameters у FastAPI

Для роботи з параметрами запиту в FastAPI використовується обʼєкт Query з бібліотеки fastapi. Давайте подивимось базовий приклад.

Крок 1: імпортуємо Query і створюємо ендпоінт

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/search")
async def search(query: str = Query(...)):
    return {"query": query}

• Query(...): Позначає, що цей параметр обов'язковий (... — це не три крапки суму, а вимога обов'язковості).
• Ми повертаємо введений параметр у відповіді, щоб перевірити роботу.

Крок 2: запускаємо сервер і тестуємо

Запускаємо застосунок:

uvicorn main:app --reload

Відкрийте в браузері http://127.0.0.1:8000/docs. Там буде наш ендпоінт /search, де можна ввести значення параметра query.

Приклад запиту:

http://127.0.0.1:8000/search?query=fastapi

Відповідь:

{
    "query": "fastapi"
}

Момент істини!

Якщо параметр query не передано, ви отримаєте помилку валідації:

{
    "detail": [
        {
            "loc": ["query", "query"],
            "msg": "field required",
            "type": "value_error.missing"
        }
    ]
}

FastAPI дбає про нас і автоматично додає валідацію. Менше багів — більше кайфу.

---

Опціональні параметри

Користувачі ліниві, і це факт. Ми не можемо очікувати, що вони завжди надішлють всі параметри. Зробімо параметр необов'язковим.

@app.get("/search")
async def search(query: str = Query(None)):
    if query:
        return {"query": query}
    return {"message": "No query provided"}

Тут:

• Query(None) вказує, що значення за замовчуванням — None.
• Ми перевіряємо наявність параметра і повертаємо повідомлення, якщо його немає.

Тестуємо:

http://127.0.0.1:8000/search

Відповідь:

{
    "message": "No query provided"
}

---

Значення за замовчуванням

Припустимо, ми хочемо, щоб якщо значення не вказано, пошуковий запит був "python":

@app.get("/search")
async def search(query: str = Query("python")):
    return {"query": query}

Тепер запит без параметра поверне:

{
    "query": "python"
}

---

Валідація параметрів

Робота з параметрами запиту — це не лише витяг даних, але й їхня валідація. Ніхто не хоче приймати запити на кшталт ?page=лодка.

Додамо валідацію для параметра page:

@app.get("/items")
async def get_items(page: int = Query(1, ge=1, le=100)):
    return {"page": page}

• ge=1: Значення має бути більше або рівне 1.
• le=100: Значення має бути менше або рівне 100.

Тестуємо:

Вказуємо page=101 — отримаємо помилку:

{
    "detail": [
        {
            "loc": ["query", "page"],
            "msg": "ensure this value is less than or equal to 100",
            "type": "value_error.number.not_le",
            "ctx": {
                "limit_value": 100
            }
        }
    ]
}

FastAPI подбав про все за вас. Дійсно зручно, правда?

---

Додаткові можливості Query

Для вбудованої документації корисно давати опис параметрів. Це робиться через аргумент description:

@app.get("/search")
async def search(
    query: str = Query("python", description="Search term to look for")
):
    return {"query": query}

Тепер у Swagger UI ви побачите опис поруч із параметром.

Регулярні вирази

Якщо потрібно жорстко обмежити введені дані, використовуйте параметр regex:

@app.get("/validate")
async def validate(
    code: str = Query(..., regex="^[A-Za-z0-9]{6}$")
):
    return {"code": code}

Цей код приймає тільки рядки довжиною 6 символів, що містять букви і цифри.

Приклад запиту:

http://127.0.0.1:8000/validate?code=abc123

Відповідь:

{
    "code": "abc123"
}

Якщо код не підходить, буде помилка:

{
    "detail": [
        {
            "loc": ["query", "code"],
            "msg": "string does not match regex \"^[A-Za-z0-9]{6}$\"",
            "type": "value_error.str.regex",
            "ctx": {
                "pattern": "^[A-Za-z0-9]{6}$"
            }
        }
    ]
}

---

Кілька параметрів

FastAPI дозволяє обробляти кілька параметрів одночасно. Додамо сортування і фільтрацію:

@app.get("/products")
async def get_products(
    category: str = Query(None),
    sort: str = Query("asc", regex="^(asc|desc)$")
):
    return {"category": category, "sort": sort}

Приклад запитів:

http://127.0.0.1:8000/products?category=books&sort=desc

Відповідь:

{
    "category": "books",
    "sort": "desc"
}

---

Поглиблюємося: Списки в Query Parameters

Іноді потрібно передати кілька значень для одного параметра. Це легко вирішується:

@app.get("/tags")
async def get_tags(tags: list[str] = Query(None)):
    return {"tags": tags}

Запит:

http://127.0.0.1:8000/tags?tags=python&tags=fastapi

Відповідь:

{
    "tags": ["python", "fastapi"]
}

І все — ніяких додаткових бібліотек.

---

Типові помилки та нюанси

Якщо ви забули вказати значення за замовчуванням або не позначили параметр як обов'язковий, FastAPI видасть помилку. Ще одна пастка — неправильна робота з типами даних. Наприклад, якщо ви очікуєте int, а користувач передає рядок, FastAPI поверне 422 HTTP-помилку.

---

Практичне застосування

• Фільтрація даних: створення API для фільтрації товарів за категоріями чи параметрами.
• Сортування: зручна передача параметрів asc/desc для контролю сортування.
• Пагінація: просте вказання сторінки і ліміту результатів.

Тепер ви знаєте, як використовувати Query Parameters для створення гнучких і зручних API. Переходьте до наступної теми, і FastAPI і далі буде вас тішити. 😉