URL: адрес, path, query-параметры
↑ 1.2 HTTP и REST для не-разработчиков · ← Предыдущая · → Следующая
Зачем это аналитику и PM
Фильтр «не работает» часто оказывается лишним символом в адресе или параметром, который ушёл не в ту часть URL. Умение разобрать адрес спасает от спора, баг это в кнопке или в контракте списка.
План темы
- схема, хост, порт
- path-параметры
- query-строка
- кодирование символов
- примеры
Объяснение
URL (Uniform Resource Locator, указатель ресурса) — адрес, по которому клиент находит ресурс: как соединиться и какой путь спросить внутри сервера.
Как адрес дома. Схема — способ доставки, хост — город и улица сервера, порт — конкретная дверь. Path — этаж и квартира. Query после вопросительного знака — записка «только новые, не больше двадцати». Метка после решётки, fragment, до API обычно не доезжает: её оставляет себе браузер.
Схема, хост, порт
https — соединение с шифрованием, http — без него. Хост — имя вроде api.example.com или IP-адрес. Порт — число двери. Для https молчаливый порт 443, для http — 80, их часто не пишут. https://api.example.com/orders и тот же адрес с :443 для стандартного порта означают одну дверь. Нестандартный порт пишут явно, иначе попадёте не на тот процесс.
Имя хоста выбирает ещё и стенд. test.example.com и api.example.com могут отдавать один и тот же путь с разными данными. Сначала читайте хост, потом путь.
Path и query
Path идёт сразу после хоста и собран из кусков через /. Кусок, который подставляют из данных, называют path-параметром: в /orders/1042 число 1042 выбирает заказ. Query начинается с ?. Пары имя=значение соединяют знаком &.
Фильтры, страница и сортировка чаще живут в query, идентификатор сущности — в path. Это удобная привычка, не закон. Если команда положила фильтр в path, в постановке копируют их адрес, а не «правильный» из статьи.
Кодирование
Пробел, кириллица, ? и & внутри значения ломают разбор, если вписать их как есть. Их заменяют процентной записью: пробел часто выглядит как %20. В query у старых форм пробел иногда приходит как +. Тогда настоящий плюс в значении тоже кодируют, иначе он станет пробелом. Адрес не склеивают вручную из кусков с пользовательским текстом: для этого есть функция клиента. Иначе поиск «А и Б» обрежется на символе &.
| Часть | Пример куска | Зачем |
|---|---|---|
| Схема | https | Шифрование и способ соединения |
| Хост | api.example.com | Какой сервер и часто какой стенд |
| Порт | 443 | Какая дверь, если она не стандартная |
| Path | /orders/1042 | Какой ресурс |
| Query | ?status=new&limit=20 | Уточнение выборки |
| Fragment | #pay | Метка для браузера, сервер API её не видит |
Примеры
Схема адреса для постановки. Домен example.com зарезервирован под примеры, такого сервера у вас нет.
https://api.example.com/orders/1042?status=new&limit=20Разбор: схема https, хост api.example.com, порт не указан и значит 443, path /orders/1042, query-параметры status и limit. Тела у такого чтения обычно нет: всё условие уже в адресе.
Живой URL учебного сервиса устроен так же, только без вашего фильтра:
https://jsonplaceholder.typicode.com/todos/1Здесь path-параметр — 1. Query нет. Пробел в значении кодируют. Поиск слова «red mug» в query выглядит как q=red%20mug, а не как адрес с дыркой посередине.
Нюансы и подводные камни
- Токен и пароль в query попадают в журналы, историю браузера и скриншоты. Им место в заголовке допуска, не в адресе.
- Лишний или пропавший
/в конце path иногда другой маршрут. Копируйте путь из спецификации целиком. - Регистр в path может различать ресурсы.
Newиnewне считайте одним значением, пока команда так не написала.
Практика
Возьмите один адрес из документации или из вкладки сети. Разложите его на схему, хост, path и query. Отметьте, какой кусок path является идентификатором.
Ожидаемый результат: таблица из четырёх строк и отдельная пометка «id заказа — вот этот кусок» либо «идентификатора в path нет». Символ, который пришлось кодировать, назван отдельно, если он есть. Секретов в адресе нет.
Вопросы с ответами
Чем path-параметр отличается от query?
Path выбирает ресурс в иерархии адреса, как номер заказа. Query уточняет выборку: фильтр, размер страницы, порядок. Куда класть поле, в итоге решает контракт, но путать эти места в баге нельзя.
Почему порт часто не написан?
У
httpsиhttpесть общеизвестные порты 443 и 80. Клиент подставляет их сам. Писать число нужно, когда сервис слушает другую дверь.
Куда девается часть адреса после решётки?
Это fragment. Браузер оставляет его у себя и на сервер API не отправляет. Серверные логи по этой метке пустые, и это нормально.