Каково назначение query-параметров в URL?

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

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

• Фильтрация: Отбор данных по определенным критериям. GET /api/products?category=electronics&in_stock=true
• Сортировка: Указание поля и порядка сортировки. GET /api/articles?sort_by=date&order=desc
• Пагинация: Разделение большого объема данных на страницы. GET /api/comments?page=2&limit=20
• Поиск: Передача поискового запроса. GET /api/search?q=python+async

Пример реализации в FastAPI:

from fastapi import FastAPI
from typing import Optional

app = FastAPI()

# q - опциональный query-параметр
@app.get("/items/")
async def read_items(q: Optional[str] = None):
    if q:
        return {"search_query": q}
    return {"items": ["Item1", "Item2"]}

Пример получения в Django:

from django.http import JsonResponse

def item_list(request):
    # request.GET - это словарь с query-параметрами
    # .get('q', None) безопасно извлекает значение или возвращает None
    search_term = request.GET.get('q', None)

    if search_term:
        # Логика поиска по search_term...
        return JsonResponse({"filtered_by": search_term})

    # Логика для возврата всех элементов
    return JsonResponse({"items": ["Item1", "Item2"]})

В отличие от параметров пути (path parameters), которые идентифицируют конкретный ресурс (например, /users/123), query-параметры модифицируют или уточняют запрос к коллекции ресурсов.