Проектирование URL + REST

URL (англ. Uniform Resource Locator) — единообразный определитель местонахождения ресурса

Структура URL

<схема>:[//[<логин>:<пароль>@]<хост>[:<порт>]][/<URL‐путь>][?<параметры>][#<якорь>]схемасхема обращения к ресурсу; в большинстве случаев имеется в виду сетевой протоколлогинимя пользователя, используемое для доступа к ресурсупарольпароль указанного пользователяхостполностью прописанное доменное имя хоста в системе DNS или IP-адрес.портпорт хоста для подключения. Для http схемы используется по-умолчанию 80.URL-путьуточняющая информация о месте нахождения ресурса; зависит от протокола.параметрыстрока запроса с передаваемыми на сервер (методом GET) параметрами. Начинается с символа ?, разделитель параметров — знак &. Пример: ?параметр_1=значение_1&параметр_2=значение_2&параметр3=значение_3якорьидентификатор «якоря» с предшествующим символом #. Якорем может быть указан заголовок внутри документа или атрибут id элемента. По такой ссылке браузер откроет страницу и переместит окно к указанному элементу.

В рамках статьи интерес представляет частный случай струкуры
http[s]://<хост>[/<URL‐путь>][?<параметры>][#<якорь>]

Важно отметить, что часть URL до # интерпретируется web сервером, после # (якорь) — браузером.

Best practices

Неизменяемые URL

Как сказал Тим Бернерс-Ли в 1998 году «Клёвые URI не меняются». Структура URL не должна содержать ничего, что может со временем измениться. Пользователи должны иметь возможность открыть сохранённую закладку через несколько лет.

Человекочитаемые URL

Для идентификаторов страниц не надо использовать хэши (строка случайных символов), нечтно вроде /3D8C811D-4352-654FDFS79FS2. Намного лучше подойдет /news/about-cats. Хэши используются в особых случаях, например:

пользователь не имеет аккаунта на сайте, но необходимо сохранить произведённые расчёты, чтобы в дальнейшем к ним вернуться.
пользователю необходимо сгененрировать уникальную одноразовую ссылку для восстановления пароля.

Доступность страницы по ID и ID-slug

Неплохой практикой является создание страниц с идентификаторами (/publications/336) с возможностью добавления полного пути (/publications/336-gis-address-plan), когда это необходимо, при этом оставляя доступ к странице по идентификатору.

Короткие URL

URL следует делать как можно короче. Они легче запоминаются.

В URL не должно быть расширения файлов

URL-адреса должны быть свободны от .php, .aspx, .html и т.д. В случае смены языка сервера будет необходимо обработать каждую страницу.

Не использовать символы, отличные от ASCII.

В общем случае лучше избегать национального алфавита. президент.рф кончено неплохо, но лучше kremlin.ru. При необходимости лучше иметь домен на латинце и редирект на него с кириллицы.

Даты следует кодировать YYYY/MM/DD

Избегайте других форматов /YYYY-MM-DD/ или /YYYYMMDD/, потому что они сложнее воспринимаются и менее дружелюбны пользователю. https://tyapk.ru/blog/archive/2018/6 однозначно лучше https://tyapk.ru/blog/archive/20186

Hackable URL

В хорошо спроектированном URL-адресе пользователь может изменить или удалить часть пути и получить ожидаемый результат. Например страница https://tyapk.ru/blog/archive/2018/6 выводит посты за июнь 2018 года. Если в URL заменить 2018 на 2017, то полученная страница должна выводить посты за июнь 2017 года. А если удалить /6, то пользователь должен получить посты за выбранный год.

Пространства имён (разделы)

<раздел1>/<раздел2>/<раздел3>

Раздел верхнего уровня пути является самым ценным в URL-адресе. Если разрабатываемый сайт позволяет пользователям зарегистрироваться и иметь свой собственный URL-адрес на верхнем уровне, следует создать черный список имен пользователей, содержащих все текущие и возможные будущие функции, которые могут возникнуть.

Например в ВК просмотр профилей доступен через идентификаторы пользователей с префиксом id, например /id1, /id123456, id765432, а также есть именованые адреса страниц пользователей, например /durov, /brezhnev, /putin. Но при этом существуют разделы /friends, /feed, /settings, /im. Соответственно пользователи сервиса не должны иметь возможность выбрать /friends, /settings или /id<номер> в качестве своего адреса страницы.

Раздел за именем пользователя является отличным решением для функций, связанных с выбранным пользователем, например:

/octobercms/followers — подписчики пользователя octobercms
/octobercms/likes — лайки пользователя octobercms

Настройки учетной записи не должны распологаться за именем пользователя. Они располагаются в /account или /settings. Кроме того, не следует путать пользователя добавляя некоторые функции в /feature/<имя_пользователя>, а другие — в <имя_пользователя>/feature.

Если сайт начинается как блог, но ожидается его расширение в будущем, имеет смысл размещать все посты в /blog/ в качестве раздела верхнего уровня, чтобы избежать возможных конфликтов позже.

Подстраницы разделов

Рассмотрим наиболее распространённый вариант на примере раздела настроек /settings из 3 страниц:

Общее — /settings
Оповещения — /settings/notifications
Приложения — /settings/applications.

При этом существует альтернативная стратегия организации первой страницы. Общее располагается по адресу /settings/account, при этом путь /settings редиректит на неё.

Соблюдайте соглашения сообщества об именовании

Маршруты ресурсов принято писать во множественном числе articles/1, (не принято article/1).

Дефисы в качестве разделителя слов

Символы подчеркивания не прижились, и у них нет ощутимых преимуществ перед дефисами. /about-us/ вместо /about_us

Немного о REST

В URL не используются глаголы.

/publications — Хорошо, название ресурса в множественном числе
/get-publications — Плохо, не следует использовать глаголы
/all-publications — Плохо

Проектирование URL происходит вокруг ресурсов.

/publications — Получить список всех публикаций
/publications/7 — Получить публикацию №7

Для реализации отношений добавляются разделы

/authors/12/publications - Получить список публикаций автора №12
/authors/12/publications/3 - Получить публикаций №3 автора №12

Следует избегать структуры сложнее collection/item/collection

Версионирование

При разработке всегда версионируйте API. /api/v1/publications