Ресурсы
и адреса

§1Ресурс — то, у чего есть адрес

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

Ресурсы находят в предметной области, а не в коде. В службе поддержки это обращение. В интернет-магазине — товар, заказ, корзина. В библиотеке — книга и выдача. В расписании занятий — занятие, аудитория, группа. Хорошая проверка: если вы можете описать вещь фразой «список таких-то» и «конкретный такой-то» — перед вами ресурс.

Обратите внимание: в таблице нет ресурсов «авторизация», «поиск», «отчёт». Это действия, а не вещи. Для них тоже находят форму — обычно это либо параметр коллекции (?status=open), либо отдельный ресурс результата. Если же начинать проектирование с действий, в адресах появляются глаголы: /doSearch и подобные.

§2Коллекция и элемент

У ресурса два вида адресов, и они означают разное. Адрес коллекции обозначает все объекты сразу, адрес элемента — один конкретный.

/api/v1/tickets                  # коллекция: все обращения
/api/v1/tickets/{ticket_id}      # элемент: одно обращение

От вида адреса зависит, какие методы уместны. На коллекцию отправляют GET (получить список) и POST (создать новый объект). К элементу обращаются GET, PATCH и DELETE. Метод POST на элемент означал бы «создай внутри конкретного обращения», и такой смысл нужно специально объяснять.

§3В адресе только существительные

Чаще всего в адресах нарушают именно это правило — записывают в путь действие:

Глагол в адресе имеет три следствия. Первое: контракт начинает противоречить сам себе — GET /deleteUser обещает чтение методом и удаление словом. Второе: клиент не может предсказать адреса. Узнав /getTickets и /createTicket, он не выведет из них имя третьей операции — вариантов слишком много. Третье: посредники между клиентом и сервером принимают решения по методу. Кэш вправе повторно отдать ответ на GET, а прокси — повторить неудавшийся GET. Если за GET скрыто удаление, повтор удалит второй объект.

Проверка адреса на слух: прочитайте его вслух без метода. Если получилось предложение с глаголом — адрес придётся исправить.

§4Путь или параметр: где чему место

Идентификатор ресурса — часть адреса. Условия выборки — параметры после знака вопроса. Смешение этих ролей ломает смысл адреса.

GET /api/v1/tickets/8d45c3e2-7f1a-4c55-9a39-2b1f0e6d4a10
GET /api/v1/tickets?status=open&limit=20&offset=0

GET /api/v1/tickets?id=8d45c3e2-…     # адрес указывает на коллекцию,
                                      # а имелся в виду один объект

Первый запрос читается как «дай обращение с таким идентификатором»: адрес указывает на конкретную вещь. Второй читается как «дай коллекцию, но отфильтруй по идентификатору» — и обращение к несуществующему объекту вернёт пустой список вместо 404. Клиенту придётся проверять длину массива вместо того, чтобы посмотреть на код ответа.

Различают их так: если без части адреса запрос теряет смысл, это path parameter. Если без неё запрос по-прежнему осмыслен, но возвращает больше данных, это query parameter.

§5Идентификатор: почему не 1, 2, 3

В учебном проекте идентификатор обращения — UUID вида 8d45c3e2-7f1a-4c55-9a39-2b1f0e6d4a10, а не порядковый номер. Причин две, и обе относятся к контракту, а не к базе данных.

Первая — безопасность. Последовательные номера подсказывают чужие адреса: увидев /tickets/42, легко перебрать соседние. Если сервер не проверяет права на каждый объект, перебор даст чужие обращения. Этот класс уязвимостей стоит первым в списке OWASP API Security Top 10 и называется Broken Object Level Authorization. Переход на UUID не заменяет проверку прав, но убирает возможность угадать адрес.

Вторая — независимость от хранилища. Порядковый номер обычно приходит из счётчика в базе. Как только сервис разделится на два экземпляра или база сменится, счётчик станет проблемой. UUID выдаёт сам сервис, не спрашивая никого.

§6Вложенность и её границы

Ресурсы бывают связаны: у пользователя есть обращения, у обращения — комментарии. Такие связи выражают вложенным адресом:

GET /api/v1/users/{user_id}/tickets       # обращения этого пользователя
GET /api/v1/tickets/{ticket_id}/comments  # комментарии этого обращения

Вложенность удобна, пока она короткая. Адрес из пяти уровней /companies/{id}/departments/{id}/users/{id}/tickets/{id}/comments заставляет клиента знать всю цепочку идентификаторов ради одного комментария. Если комментарий существует сам по себе, у него должен быть и собственный адрес.

§7Проверка адресов правилом

Правило «в адресе только существительные» живёт в файле правил проекта — и там же превращается в машинную проверку. В учебном проекте это правило paths-no-verbs в .spectral.yaml.

  paths-no-verbs:
    description: URI MUST описывать ресурс существительным, а не действием.
    severity: error
    given: "$.paths"
    then:
      field: "@key"
      function: pattern
      functionOptions:
        notMatch: "/(get|create|update|delete|remove|add)[A-Za-z]*(/|$)"

Проверим этим правилом описание, в котором адреса нарушают договорённость. Вывод ниже — настоящий результат запуска линтера:

10:22    error  paths-no-verbs             URI MUST описывать ресурс существительным,
                                          а не действием.          paths./api/v1/getTickets
11:9     error  operation-operationId      Operation must have "operationId".
47:19    error  json-properties-snake-case Свойства JSON MUST быть записаны в snake_case.

✖ 9 problems (7 errors, 2 warnings, 0 infos, 0 hints)

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