Чем различаются path-параметры и query-параметры в REST API и когда что использовать?

Короткий ответ

Path-параметры — часть URL, идентифицирующая конкретный ресурс (/users/42); query-параметры — необязательные модификаторы запроса после ? (?page=2&status=active), используемые для фильтрации, сортировки, пагинации.

Как это работает подробнее

path-параметр обычно обязателен и однозначно определяет ресурс в иерархии URL; query-параметры опциональны и не меняют "адрес" ресурса, а уточняют, какую выборку или представление вернуть.

Пример кода

example.pyКопировать

from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/users/{user_id}/orders")
def list_orders(
    user_id: int,
    status: str | None = Query(default=None),
    page: int = Query(default=1, ge=1),
):
    # user_id — path-параметр, обязателен; status и page — query-параметры, опциональны
    return {"user_id": user_id, "status": status, "page": page}

Что использовать на практике

• Рекомендация. если без параметра запрос не имеет смысла (например, ID пользователя) — это path-параметр; если параметр можно не указывать и получить разумный результат по умолчанию (фильтр, лимит) — это query-параметр. Такое разделение упрощает кэширование и генерацию документации (OpenAPI).

Подводные камни

• Риски. засовывать в path опциональные фильтры (/users/active/42), что усложняет маршрутизацию и делает URL негибким; передавать идентификатор ресурса как query-параметр (/users?id=42), когда это должен быть path-параметр, что путает смысл "коллекция + фильтр" с "конкретный ресурс".