Параметры пути (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 гибким и функциональным.