Что такое query-параметры в HTTP-запросах

Query-параметры (параметры запроса) — это часть URL, используемая для передачи данных на сервер в виде пар ключ=значение. Они следуют за знаком вопроса (?) и разделяются амперсандом (&).

Они не изменяют сам ресурс (путь), а уточняют запрос к нему.

Основные сценарии использования:

• Фильтрация: ?status=active&author_id=123
• Сортировка: ?sort_by=date&order=desc
• Пагинация: ?page=2&limit=10
• Поиск: ?q=fastapi+tutorial

Пример URL: https://api.example.com/items?limit=20&sort_by=price&status=available

Пример обработки в FastAPI (Python):

FastAPI автоматически извлекает, преобразует и валидирует параметры из URL на основе аннотаций типов.

from fastapi import FastAPI
from typing import Optional

app = FastAPI()

@app.get("/items/")
async def read_items(q: Optional[str] = None, limit: int = 10, is_active: bool = True):
    """
    Принимает параметры:
    - q: необязательная строка для поиска
    - limit: целочисленный лимит (по умолчанию 10)
    - is_active: булевый флаг (по умолчанию True)
    """
    query_params = {"q": q, "limit": limit, "is_active": is_active}
    # ... логика фильтрации данных на основе query_params ...
    return {"params_received": query_params}

# Пример запроса к этому эндпоинту:
# /items/?q=my-item&limit=50&is_active=false

Ключевые характеристики:

• Они видны в URL, поэтому не подходят для передачи конфиденциальных данных (паролей, токенов).
• Всегда передаются как строки, и сервер отвечает за их преобразование в нужные типы (например, int, bool).
• Являются стандартным и универсальным способом уточнения GET-запросов.