URI и query-параметры

Что такое URI

URI (Uniform Resource Identifier, унифицированный идентификатор ресурса) — строка, однозначно указывающая на ресурс. Ресурсом может быть страница, файл, эндпоинт API или что-то вовсе не сетевое — например, книга по ISBN.

Разница с соседними аббревиатурами:

• URI — общее понятие: идентификатор.
• URL (Locator) — URI, который говорит где ресурс лежит и как его достать: https://example.com/page. Все URL — это URI.
• URN (Name) — URI, который называет ресурс, не указывая местоположение: urn:isbn:9785990944169.

На практике почти всё, с чем работают в вебе, — это URL. Слово «URI» чаще встречается в спецификациях и документации API, где важна точность формулировки.

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

https://user:pass@api.example.com:8443/v1/orders?status=paid&limit=50#top
└─┬─┘   └───┬───┘ └──────┬───────┘ └┬─┘└───┬───┘ └────────┬─────────┘└┬┘
scheme  userinfo        host       port   path          query      fragment

Фрагмент после # обрабатывает только браузер — в логах Nginx его не будет, и в API он бесполезен.

Query-параметры

Query (строка запроса) — часть URI после ?, набор пар ключ=значение, разделённых &. Ими не выбирают ресурс, а уточняют, каким он должен быть: фильтры, сортировка, пагинация, формат ответа.

# Фильтр, сортировка и постраничная выдача
curl -G https://api.example.com/v1/orders \
  --data-urlencode "status=paid" \
  --data-urlencode "created_after=2026-01-01" \
  --data-urlencode "sort=-created_at" \
  --data-urlencode "limit=50"

Слово «query» многозначно: в вебе это строка запроса в URL, в базах данных — SQL-запрос. Общий смысл один — «запрос», а конкретика определяется контекстом.

Что стоит помнить о query-параметрах:

• Единого стандарта для массивов нет. ?id=1&id=2, ?id[]=1&id[]=2 и ?id=1,2 — все три варианта живые, и парсит их каждый фреймворк по-своему. Смотрите документацию сервиса.
• Кодирование обязательно. Пробел, кириллица, &, + и # внутри значения ломают разбор, если их не закодировать: пробел → %20, & → %26. В curl за это отвечает --data-urlencode.
• Query-строка светится везде. Она попадает в логи сервера, историю браузера и заголовок Referer — поэтому API-ключи и токены передают заголовком, а не параметром.
• Длина ограничена. Жёсткого лимита в стандарте нет, но у браузеров и веб-серверов есть свои пределы на размер строки запроса. Огромные списки фильтров передают телом через POST.

Что такое GET

GET — HTTP-метод чтения: «отдай мне ресурс по этому URI». Всё, что нужно передать, идёт в пути и query-параметрах, тела у GET-запроса, как правило, нет.

Отсюда свойства метода: GET-запрос можно кешировать, повторять и класть в закладки, и он не должен ничего менять на сервере. Ссылка GET /orders/42/delete — классическая ошибка: любой краулер или префетч браузера пройдёт по ней и удалит заказ. Изменения делают через POST, PATCH, DELETE.

URI и Web UI

Похожие на слух, но не связанные вещи. URI — адрес ресурса. Web UI (Web User Interface) — веб-интерфейс: панель управления в браузере вместо командной строки. Так называют, например, веб-панель Portainer или интерфейс роутера. Общее у них только то, что у любого Web UI есть свой URL.

Связанные термины

• API endpoint — адрес конкретной операции API
• HTTP — где применяются методы GET и POST
• Домен — часть host в URI
• Пагинация — самый частый случай query-параметров
• API-ключи — то, что нельзя класть в query