Робота з Query Parameters для передачі даних

Сьогодні ми йдемо далі й поговоримо про Query Parameters — один із найважливіших інструментів для передачі даних у веб-запитах. З їх допомогою можна додати гнучкості у взаємодію з API без потреби змінювати маршрути або тіло запитів.

Уявіть, що ви заходите в інтернет-магазин і шукаєте ноутбук з певною ціною та брендом. Ви вводите параметри пошуку, а сервер повертає результат, що відповідає вашим запитам. Ці параметри пошуку, які передаються через URL, і називаються Query Parameters.

У HTTP-запитах Query Parameters додаються після знака ? в URL. Приклад:

GET /products?category=laptop&brand=apple&price=1500

Ось:

• category — це ім'я параметра,
• laptop — значення параметра,
• Параметри відокремлюються один від одного символом & (brand=apple&price=1500).

---

Приклад використання Query Parameters

Давайте створимо API, яке повертає список товарів. Ми будемо використовувати Query Parameters для фільтрації товарів за категорією і ціною.

from fastapi import FastAPI, Query
from typing import Optional

app = FastAPI()

# Список "товарів" для демонстрації
products = [
    {"id": 1, "name": "Laptop", "category": "electronics", "price": 1500},
    {"id": 2, "name": "Phone", "category": "electronics", "price": 800},
    {"id": 3, "name": "T-Shirt", "category": "clothing", "price": 20},
    {"id": 4, "name": "Jeans", "category": "clothing", "price": 50},
]

@app.get("/products")
async def get_products(
    category: Optional[str] = Query(None),  # Допустима категорія
    max_price: Optional[float] = Query(None)  # Максимальна ціна
):
    filtered_products = products

    if category:
        filtered_products = [p for p in filtered_products if p["category"] == category]
    
    if max_price:
        filtered_products = [p for p in filtered_products if p["price"] <= max_price]
    
    return {"products": filtered_products}

Пояснення коду

• Query(None): Ми використовуємо функцію Query з FastAPI, щоб вказати, що параметр може бути переданий через Query Parameters. Значення None робить параметр необов'язковим.
• category і max_price адаптують результат залежно від вхідних даних. Якщо параметри не передані, повертаються всі записи.

---

Перевірка роботи

Спробуємо кілька запитів:

1. Отримати всі товари:

   GET /products

   Відповідь:

   {
     "products": [
       {"id": 1, "name": "Laptop", "category": "electronics", "price": 1500},
       {"id": 2, "name": "Phone", "category": "electronics", "price": 800},
       {"id": 3, "name": "T-Shirt", "category": "clothing", "price": 20},
       {"id": 4, "name": "Jeans", "category": "clothing", "price": 50}
     ]
   }

2. Отримати товари тільки з категорії clothing:

   GET /products?category=clothing

   Відповідь:

   {
     "products": [
       {"id": 3, "name": "T-Shirt", "category": "clothing", "price": 20},
       {"id": 4, "name": "Jeans", "category": "clothing", "price": 50}
     ]
   }

3. Отримати товари дешевше $1000:

   GET /products?max_price=1000

   Відповідь:

   {
     "products": [
       {"id": 2, "name": "Phone", "category": "electronics", "price": 800},
       {"id": 3, "name": "T-Shirt", "category": "clothing", "price": 20},
       {"id": 4, "name": "Jeans", "category": "clothing", "price": 50}
     ]
   }

---

Опціональні параметри і значення за замовчуванням

Query Parameters в FastAPI можна зробити необов'язковими, задавши значення за замовчуванням. Наприклад:

async def get_products(
    category: str = Query(None),
    max_price: float = Query(1000)  # Значення за замовчуванням: 1000
):
    pass

Якщо користувач не передасть max_price, він автоматично прийме значення 1000.

---

Валідація Query Parameters

FastAPI + Pydantic = ❤️. Завдяки вбудованій підтримці Pydantic, ви можете додати правила для валідації Query Parameters.

Приклад з додаванням обмежень:

@app.get("/products")
async def get_products(
    category: Optional[str] = Query(None, max_length=50),  # Максимальна довжина рядка
    max_price: Optional[float] = Query(None, gt=0)  # Ціна повинна бути більше 0
):
    filtered_products = products
    
    if category:
        filtered_products = [p for p in filtered_products if p["category"] == category]
    
    if max_price:
        filtered_products = [p for p in filtered_products if p["price"] <= max_price]
    
    return {"products": filtered_products}

Тепер FastAPI буде повертати 400 Bad Request, якщо:

1. category довше 50 символів.
2. max_price менше або рівне 0.

---

Обробка списку значень в Query Parameters

Іноді потрібно передати кілька значень для одного параметра. Наприклад, щоб вибрати товари з кількох категорій.

FastAPI підтримує цей сценарій "з коробки":

@app.get("/products")
async def get_products(
    categories: Optional[list[str]] = Query(None)  # Категорії у вигляді списку
):
    filtered_products = products
    
    if categories:
        filtered_products = [p for p in filtered_products if p["category"] in categories]
    
    return {"products": filtered_products}

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

GET /products?categories=electronics&categories=clothing

Відповідь:

{
  "products": [
    {"id": 1, "name": "Laptop", "category": "electronics", "price": 1500},
    {"id": 2, "name": "Phone", "category": "electronics", "price": 800},
    {"id": 3, "name": "T-Shirt", "category": "clothing", "price": 20},
    {"id": 4, "name": "Jeans", "category": "clothing", "price": 50}
  ]
}

---

Поширені помилки при роботі з Query Parameters

Часто зустрічаються проблеми:

1. Відсутність валідації. Якщо ви не обмежуєте введені дані (наприклад, використовуєте max_length), користувачі можуть ненароком (або навмисно) відправити гігантський рядок або некоректні значення.
2. Неправильно оброблені значення за замовчуванням. Якщо ви задаєте значення за замовчуванням, переконайтесь, що воно відповідає логіці вашого застосунку. Наприклад, якщо max_price за замовчуванням рівний 1000, це може обмежити повернені результати.
3. Плутанина між Query Parameters і Path Parameters. Запам'ятайте: Query Parameters — це параметри в URL після ?. Path Parameters є частиною самого маршруту.

---

Переваги Query Parameters у реальних проєктах

1. Фільтрація даних. Наприклад, в інтернет-магазині можна використовувати Query Parameters для пошуку товарів за категоріями, цінами та іншими ознаками.
2. Найменування параметрів. На відміну від структури тіла запиту, Query Parameters більш "читабельні" прямо з URL.
3. Інтеграція з фронтендом. Більшість фронтенд-фреймворків, таких як React і Angular, легко працюють з Query Parameters для побудови динамічних запитів до сервера.

---

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