Параметри шляху (Path Parameters) в маршрутизації

Параметри шляху в FastAPI використовуються для передачі змінних у URL. Вони дозволяють динамічно формувати маршрути, що робить API більш гнучким. Наприклад, замість створення купи ендпоінтів для отримання даних про користувачів з різними ID (/users/1, /users/2, /users/3), ти можеш створити один маршрут /users/{user_id}, де user_id буде динамічним значенням.

Це схоже на гру в бургерну: замість того, щоб робити окреме меню для кожного відвідувача ("меню Васі", "меню Олени"), ти робиш універсальне меню і вказуєш конкретне ім'я під час замовлення. Ти економиш час, зусилля і залишаєш приємне враження у клієнтів.

---

Навіщо це потрібно?

Використання параметрів шляху — це стандартний спосіб передачі даних у REST API. У реальних проєктах це застосовується для обслуговування:

• Отримання або керування ресурсами за їхнім унікальним ідентифікатором (наприклад, /users/{user_id}).
• Фільтрації даних (наприклад, /blogs/{category}/posts).
• Забезпечення семантичної зрозумілості URL (їх легко читати й розуміти).

Практичний приклад: припустимо, ти розробляєш API для блогу. Для виведення списку статей у категорії "технології" ти можеш використати URL /articles/technology, де technology — це параметр шляху.

---

Як це працює в FastAPI?

Параметри шляху визначаються з використанням фігурних дужок ({}) для опису змінної, яку ми очікуємо в маршруті. Давай розберемо це на простому прикладі.

Приклад 1: динамічний маршрут

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

У цьому прикладі маршрут /items/{item_id} очікує, що item_id буде надано клієнтом. FastAPI автоматично перетворює його на тип даних int. Якщо клієнт відправить запит на /items/42, сервер поверне:

{
  "item_id": 42
}

Пояснення

• item_id: це змінна, передана в маршрут.
• Тип даних int: FastAPI перевіряє, що значення, передане клієнтом, можна перетворити в int. Якщо клієнт спробує передати рядок замість числа (наприклад, /items/abc), FastAPI автоматично згенерує помилку.

---

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

FastAPI підтримує валідацію значень параметрів шляху. Наприклад, ти можеш обмежити діапазон допустимих значень.

from fastapi import FastAPI, Path

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: int = Path(..., title="The ID of the item", ge=1, le=1000)):
    return {"item_id": item_id}

Тут ми використовуємо Path для валідації:

• title: опис параметра (буде видно в документації Swagger).
• ge: мінімальне значення (greater or equal to).
• le: максимальне значення (less or equal to).

Якщо клієнт відправить запит /items/0 або /items/1001, він отримає повідомлення про помилку.

---

Приклад: кілька параметрів шляху

Іноді одного параметра недостатньо, і потрібно використовувати кілька.

@app.get("/users/{user_id}/items/{item_id}")
async def read_user_item(user_id: int, item_id: str):
    return {"user_id": user_id, "item_id": item_id}

Запит /users/123/items/book42 поверне:

{
  "user_id": 123,
  "item_id": "book42"
}

---

Практичне застосування: API для керування книгами

Зробимо простий API для роботи з книгами в бібліотеці. Нехай у нас буде два ендпоінти:

1. Отримання інформації про конкретну книгу.
2. Отримання списку книг автора.

from fastapi import FastAPI, HTTPException

app = FastAPI()

# Приклад даних
books_db = {
    "1": {"title": "1984", "author": "George Orwell"},
    "2": {"title": "Brave New World", "author": "Aldous Huxley"},
    "3": {"title": "Fahrenheit 451", "author": "Ray Bradbury"},
}

@app.get("/books/{book_id}")
async def get_book(book_id: str):
    book = books_db.get(book_id)
    if not book:
        raise HTTPException(status_code=404, detail="Book not found")
    return book

@app.get("/authors/{author}/books")
async def get_books_by_author(author: str):
    books = [book for book in books_db.values() if book["author"] == author]
    if not books:
        raise HTTPException(status_code=404, detail="No books found for this author")
    return books

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

• GET /books/1 поверне інформацію про книгу з ID "1".
• GET /authors/George Orwell/books поверне список книг Джорджа Орвелла.

---

Особливості та типові помилки

Працювати з параметрами шляху досить просто, але є кілька важливих моментів:

1. Порядок маршрутів має значення.
   FastAPI перевіряє маршрути в порядку їх оголошення. Якщо в тебе є загальний маршрут, наприклад /items/{item_id}, і конкретний маршрут, наприклад /items/special, оголошуй більш специфічний маршрут раніше.

   
   @app.get("/items/special")
   async def get_special_item():
       return {"item": "This is a special item"}
   
   @app.get("/items/{item_id}")
   async def get_item(item_id: int):
       return {"item_id": item_id}
   

2. Конфлікти маршрутів.
   Якщо в тебе є маршрут /users/{username} і /users/me, запити до /users/me можуть «потрапити» в маршрут /users/{username}. Щоб уникнути цього, використай строгі перевірки типів або чітко пропиши маршрути.
3. Обов'язковість параметрів шляху.
   Усі параметри шляху обов'язкові. Якщо ти не передаси параметр, FastAPI поверне помилку 404.
4. Валідація типів.
   FastAPI автоматично перетворює значення у вказаний тип. Якщо перетворення неможливе, сервер поверне помилку. Це захистить твою програму від несподіваних даних.

---

Взаємодія з фронтендом

Параметри шляху — це крутий спосіб зробити інтеграцію фронтенду з сервером зручнішою. Наприклад, фронтенд-розробник може легко формувати запити до твого API:

const userId = 123;
const response = await fetch(`/users/${userId}/items`);
const items = await response.json();

Таким чином, параметри шляху роблять API більш «читабельним» і передбачуваним.

---

Розширені можливості

FastAPI дозволяє використовувати складні типи об'єктів у параметрах шляху. Наприклад, ти можеш передавати складні дані в форматі JSON з допомогою бібліотеки Pydantic. Однак цю тему ми залишимо для майбутніх лекцій.

На цьому етапі ти вже можеш створювати маршрути з динамічними параметрами шляху, валідацією і детальною обробкою помилок, що робить твій API гнучким і функціональним.