Что такое path parameters и query parameters в FastAPI?

Что такое path parameters

Path parameters — это параметры, встроенные в путь URL. Обычно они идентифицируют конкретный ресурс: статью, пользователя, заказ или другой объект.

from fastapi import FastAPI

app = FastAPI()


@app.get('/articles/{article_id}')
def get_article(article_id: int):
    return {'article_id': article_id}

В этом примере запрос GET /articles/42 передаст в функцию значение article_id=42. FastAPI преобразует значение к указанному типу int и вернёт ошибку валидации, если передано некорректное значение.

Что такое query parameters

Query parameters передаются после ? в URL и разделяются символом &. Они обычно не определяют сам ресурс, а уточняют способ его получения: фильтры, страницу, лимит, сортировку или поиск.

@app.get('/articles')
def get_articles(limit: int = 20, offset: int = 0, q: str | None = None):
    return {'limit': limit, 'offset': offset, 'query': q}

Запрос GET /articles?limit=10&offset=20&q=fastapi передаст соответствующие значения в endpoint.

Как FastAPI различает параметры

Если имя параметра указано в шаблоне пути, FastAPI воспринимает его как path parameter. Параметры функции, которых нет в пути и которые не описаны как тело запроса или dependency, обычно считаются query parameters.

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

Для дополнительных ограничений можно использовать Path и Query.

from fastapi import Path, Query
from typing import Annotated


@app.get('/articles/{article_id}')
def get_article(
    article_id: Annotated[int, Path(gt=0)],
    limit: Annotated[int, Query(ge=1, le=100)] = 20,
):
    return {'article_id': article_id, 'limit': limit}

Как ответить на собеседовании

Path parameters — это переменные в самом URL-пути, например идентификатор ресурса в /articles/{id}. Query parameters идут после ? и обычно нужны для фильтрации, поиска и пагинации. FastAPI валидирует оба типа параметров по type hints.