RESTful API: мы всё делаем неправильно

Привет! Прежде чем я начну, стоит немного рассказать о себе. Я не так давно занимаюсь серьезной разработкой (всего года три) и, как мне кажется, именно отсутствие многолетнего опыта часто позволяет мне смотреть на многие традиции и устоявшиеся способы выполнения стандартных задач с оригинальной точки зрения. Моя специальность — бэкенд сайтов и мобильных приложений (основной язык разработки — python3, любимый фреймворк — Django).

Сразу предупреждаю, что данная статья — не пример реализации, кода здесь нет вообще. Это скорее размышление на тему REST, аггрегирующее известные мне источники, чтобы тем, кто тоже столкнется с моей проблемой, не пришлось долго искать руководство к действию.

Причиной написания данной статьи послужил спор с моим коллегой по поводу именования сущностей REST: он утверждал, что необходимо называть их во множественном числе, например, books, я же считал (и считаю), что это нелогично, и отстаивал вариант book. Признаюсь, мы оба пошли неправильным путем — вместо того, чтобы найти оригинальную документацию к архитектуре REST, написанную её создателем Р. Филдингом ещё в 2000 году (ссылку приведу в конце), мы сначала начали придумывать логические обоснования нашим позициям, а после просто стали смотреть, как это делается в больших компаниях и, перебрав несколько вариантов, установили, что мой встречается чаще, на чем и порешили спор завершить.

Всё бы ничего, но эта же дискуссия повторилась месяц спустя с другим коллегой, который открыл документацию к создаваемому мной API и очень удивился моему способу именования. Кратко описав ему ранее приведенные аргументы, я понял, что это будет повторяться вечно, если я не разберусь, как правильно называть ресурсы.

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

За единственное число:

• Это же 'resource identifier', а не 'resources identifier'!
• А вот у Atlassian вот так: docs.atlassian.com/atlassian-confluence/REST/latest-server ^[1]
• В описании моделей нету сущности books!

За множественное число:

• Таблица в БД, скорее всего, называется во множественном числе!
• А вот у Твиттера вот так: dev.twitter.com/overview/api/tweets ^[2]
• www.restapitutorial.com/lessons/restfulresourcenaming.html ^[3]

Как вы можете видеть, аргументы довольно противоречивы, и к каждому можно придумать сотню контраргументов. Добавлю, что ссылаться на чью-то реализацию я вообще считаю достаточно бессмысленным занятием: да, Atlassian и Twitter — гиганты IT, но ведь все могут ошибаться, особенно учитывая, что делают все по-разному.

Заниматься составлением огромных списков ресурсов, которые используют разные варианты именования ресурсов REST, мне совершенно не хочется. Вместо этого я пошел читать диссертацию Филдинга, в которой определенных конвенций именования нет. Зато есть четкая формулировка концепции «resource identifier», которая, собственно, и является предметом дискуссии. Вот что пишет о ней Филдинг:

REST uses a resource identifier to identify the particular resource involved in an interaction between components. REST connectors provide a generic interface for accessing and manipulating the value set of a resource, regardless of how the membership function is defined or the type of software that is handling the request. The naming authority that assigned the resource identifier, making it possible to reference the resource, is responsible for maintaining the semantic validity of the mapping over time (i.e., ensuring that the membership function does not change).

Ну то есть по Филдингу есть некая naming authority, которая и занимается присвоением идентификаторов ресурсам, и она-то как раз и ответственна за семантическую правильность наименований. Никаких гайдлайнов по этой самой семантической правильности Филдинг нам не дал, веря, что логики достаточно. Если поискать ещё, можно найти его комментарий по похожему вопросу, который показывает всю суть его отношения к любым уточнениям и стандартизациям REST:

In regards to «untold hours wasted in debate», that is close to the goal of my dissertation — to introduce a way of thinking about software architecture that promotes honest debate about the properties that are desired and actual thought applied to the constraints chosen to achieve them (and their resulting trade-offs). It is almost never wasted, even when it is poorly informed.
…
...at best all you will get is a committee that has some vague notion
of what they consider to be design to write down the least common
denominator of misinformed «best practice» based upon whatever Microsoft
chose to implement in its last release. The IETF has made a habit of
that recently.

То есть, если совсем обобщать — «думайте сами, решайте сами, а если это стандартизировать, то получится бред и обязаловка». Ну что ж, вообще говоря, такой подход к этому вопросу гораздо лучше, чем форсинг надуманных стандартов и спецификаций, хоть он и вызывает появление множества различных реализаций и подходов, но — не есть ли это признак действительно «free-as-in-free-speech» архитектуры?

Подводя итог, можно сказать, что неправильных подходов к имплементации REST в смысле именования ресурсов, похоже, нет. Однако стоит учитывать следующее:

1. В оригинальном описании REST концепция «resource identifier» описывается как уникальный идентификатор, однозначно указывающий на ресурс. Что это за идентификатор — ID, название или хэш строкового представления — не уточняется, этот вопрос оставлен на усмотрение разработчиков с единственным условием: поддержание семантической целостности архитектуры на протяжении всего существования системы.
2. Необходимо делать архитектуру понятной для пользователя. Внутренние особенности реализации — такие, как название таблицы в БД или имя сущности в описании моделей ORM — должны отходить на второй план, а в идеале вообще не учитываться.
3. Брать в качестве примера реализацию популярного ресурса — это, несомненно, удобно. Но стоит всегда помнить, что догматическое следование чужим реализациям в перспективе приводит к спорам ни о чем.

Спасибо за внимание!

Источники:

1. Диссертация Роя Филдинга, глава 5 ^[4]
2. Википедия ^[5]
3. Комментарий самого Филдинга по сходному вопросу ^[6]
4. Документация Atlassian ^[1]
5. Документация Twitter ^[2]

Автор: feakuru

Источник ^[7]