Структура URL и query-параметры

Каждый HTTP-запрос — это обращение к конкретному адресу. Понимание структуры URL помогает не гадать, что происходит, а читать запросы как текст.

Из чего состоит URL

https://api.chucknorris.io/jokes/random?category=dev&limit=5
│      │                   │            │
│      │                   │            └── query-параметры
│      │                   └───────────── путь (path)
│      └───────────────────────────────── хост (host)
└──────────────────────────────────────── протокол (scheme)

• Протокол (https://) — способ передачи данных. Всегда используй https, не http
• Хост (api.chucknorris.io) — адрес сервера
• Путь (/jokes/random) — конкретный ресурс на сервере
• Query-параметры (?category=dev) — дополнительные данные для фильтрации или настройки

Query-параметры: синтаксис

Query-параметры начинаются с ? и записываются парами ключ=значение:

?category=dev

Несколько параметров разделяются символом &:

?category=dev&limit=5&lang=ru

Проблема ручной сборки URL

Если собирать URL вручную через f-строку, легко ошибиться:

# Плохо — ручная сборка
city = "New York"
url = f"https://api.example.com/weather?city={city}"
# Итог: ?city=New York — пробел сломает запрос!

Пробелы и спецсимволы (&, /, #, ?) в значениях нужно URL-кодировать:
- пробел → %20
- & → %26
- / → %2F

Делать это вручную — источник ошибок.

Правильный способ — params= в requests

Библиотека requests кодирует параметры автоматически:

import requests

response = requests.get(
    "https://api.chucknorris.io/jokes/random",
    params={"category": "dev"}
)
# Итоговый URL: .../jokes/random?category=dev

С пробелами тоже всё хорошо:

response = requests.get(
    "https://api.example.com/search",
    params={"q": "New York", "lang": "ru"}
)
# Итоговый URL: .../search?q=New+York&lang=ru

Посмотреть итоговый URL

Иногда полезно проверить, какой URL собрал requests:

response = requests.get(url, params=params)
print(response.url)  # покажет полный URL с параметрами

Path-параметры vs Query-параметры

Есть два способа передать данные в URL:

Path-параметр — часть пути, обязателен:

/repos/torvalds/linux/issues
       │        │
       owner    repo

Query-параметр — после ?, обычно опционален:

/repos/torvalds/linux/issues?state=open&per_page=10

API-документация всегда указывает, какой тип используется для каждого параметра.

Итог

Используй params= в requests вместо ручной сборки URL — это надёжнее и читаемее.