REST API должен основываться на гипертексте

– И вы ему поверили? – с упреком сказал уполномоченный по копытам. – Ну, как вы думаете, разве я без вашего разрешения взял бы эти гири?

Остап посмотрел на Паниковского. Только сейчас он заметил, что под его пиджаком нет уже полтинничной манишки и оттуда на свет божий глядит голая грудь. Не говоря ни слова, великий комбинатор свалился на стул. Он затрясся, ловя руками воздух. Потом из его горла вырвались вулканические раскаты, из глаз выбежали слезы, и смех, в котором сказалось все утомление ночи, все разочарование в борьбе с Корейко, так жалко спародированной молочными братьями.

Этим фрагментом из классики я хотел бы предварить перевод блог-поста Роя Т. Филдинга REST APIs must be hypertext-driven. Отдельное спасибо habr.com/users/arthuriantech ^[1] за ссылку на материал.

Эта неделя на Хабре ознаменовалась как неделя REST(Full) API. Меня в этом смысле всегда смущало наличие приставки REST в этом термине. И, как оказалась, не одного меня. Сегодня я прочитаю сам и предлагаю всем желающим узнать что об этом думал Рой Т. Филдинг в 2008 году. Конечно, кто-то нервно заерзает на стулке и скажет: передайте Рою, что Беня знает за REST API. И тем не менее начнем.

Меня приводит в уныние мысль о том, как много людей называют любой интерфейс на основе HTTP-протокола REST API. Сегодняшний пример — API REST SocialSite. Это RPC. Это вопиющее RPC. Оно демонстрирует такие жесткие связи, что ему нужно присвоить категорию жесткое порно.

Что нужно сделать, чтобы они поняли, что в архитектуре REST гипертекст является необходимым элементом? Другими словами, если механизм состояния приложения (и, следовательно, API) не основан на гипертексте, он не может быть RESTful и не может быть REST API. Точка. Какую книгу нужно переписать, чтобы это было понятно?

Разработчики API, обратите внимание на следующие правила, прежде чем называть свое создание REST API:

API REST не должен зависеть от конкретного протокола связи, хотя его успешное сопоставление с данным протоколом может зависеть от доступности метаданных, выбора методов и т. д. В общем, любой протокол в схеме URI, должен позволять любой схеме URI, быть использованной для идентификации. [Ошибка здесь подразумевает, что идентификация не отделена от взаимодействия.]

API REST не должен содержать каких-либо изменений в протоколах связи, кроме заполнения или исправления деталей недостаточно определенных битов стандартных протоколов, таких как метод PATCH HTTP или поле заголовка Link. Обходные пути для неработающих реализаций (например, таких браузеров, которые достаточно глупы, чтобы полагать, что HTML определяет набор методов HTTP) должны определяться отдельно или, по крайней мере, в приложениях, с ожиданием того, что обходной путь в конечном итоге устареет. [Ошибка здесь заключается в том, что интерфейсы ресурса являются специфическими, а не универсальными.]

API-интерфейс REST должен потратить почти все свои описательные усилия на определение типов носителей, используемых для представления ресурсов, и на управление состоянием приложения, а также на определение имен расширенных отношений и разметки с поддержкой гипертекста для существующих стандартных типов носителей. Любое усилие, затрачиваемое на описание того, какие методы использовать с какими интересующими URI, должно быть полностью определено в рамках правил обработки для типа носителя (и, в большинстве случаев, уже определено существующими типами носителя). [Ошибка здесь заключается в том, что внешняя по отношению к гипертексту информация движет взаимодействием вместо гипертекста.]

API REST не должен определять фиксированные имена ресурсов или пространств имен (жесткая связанность клиента и сервера). Серверы должны иметь свободу управления своими собственными пространствами имен. Вместо этого позвольте серверам инструктировать клиентов о том, как создавать соответствующие URI, например, в HTML-формах и шаблонах URI, определяя эти инструкции в типах мультимедиа и ссылочных отношениях. [Ошибка здесь заключается в том, что структура ресурса, задается вне этого ресурса, например в специфичном для предметной области стандарте, который является ориентированным на данные аналогом функциональной связи RPC].

REST API никогда не должен иметь «типизированных» ресурсов, значимых для клиента. Авторы спецификаций могут использовать типы ресурсов для описания реализации сервера за интерфейсом, но эти типы должны быть неактуальными и невидимыми для клиента. Единственные типы, которые важны для клиента, — это тип носителя текущего представления и стандартизированные имена отношений. [см. выше]

API REST следует вводить без каких-либо предварительных знаний, кроме начального URI и набора стандартизированных типов мультимедиа, подходящих для целевой аудитории (т. е. ожидаемых на стороне клиента, который может использовать API). С этого момента все переходы состояний приложения должны определяться выбором предоставленных сервером вариантов, которые присутствуют в полученных представлениях, или манипуляциями пользователя с этими представлениями. Переходы могут быть определены (или ограничены) знаниями клиента о типах медиа и механизмах связи с ресурсами, которые могут быть улучшены на лету (например, код по запросу). [Ошибка здесь заключается в том, что внешняя по отношению к гипертексту информация движет взаимодействием вместо гипертекста.]

Возможно, я что-то упустил, но выше приведены правила, существенные для гипертекста, которые чаще всего нарушаются в так называемых REST API. Пожалуйста, попытайтесь придерживаться их или выберите другое модное слово для своего API.

Автор: apapacy

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