owned this note
owned this note
Published
Linked with GitHub
# REST APIs must be hypertext-driven
https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
Разработчики API, пожалуйста, учитывайте следующие правила прежде чем называть свое творение REST API:
* REST API не должен быть зависимым от какого-либо единственного протокола связи, однако успешное сопоставление API с отдельно взятым протоколом может зависеть от доступности метаданных, ассортимента методов и прочего. В целом, любая часть протокола, которая использует URI для идентификации, должна позволять использовать любую схему URI которая будет использована для этой идентификации. [*Ошибка вытекает из того, что идентификация не отделена от взимодействия.*]
* REST API не должен отражать в себе каких-либо изменений в протоколах связи, кроме заполнения или исправления размытых частей протоколов, таких как метод PATCH или заголовок Link[^1].
* REST API не должен определять фиксированные имена ресурсов или иерархии (явную связь клиента и сервера). Серверы должны иметь свободу управления своим собственным пространством имен. Вместо этого позвольте серверам инструктировать клиентов о том, каким образом создавать соответствующие URI, например так, как это делается в [HTML-формах](https://developer.mozilla.org/ru/docs/Learn/HTML/Forms/Отправка_и_Получение_данных_формы#Метод_GET) и [шаблонах URI](https://en.wikipedia.org/wiki/URL_Template), путем определения этих инструкций в рамках media-типов[^2] и [отношений ссылок](https://developer.mozilla.org/ru/docs/Web/HTML/Element/ссылка). [*Ошибка вытекает из того, что клиенты подразумевают структуру ресурса исходя из внеполосной информации[^3], такой как стандарт предметной области, что является эквивалентом функциональной связи RPC, но ориентированным на данные.*]
* REST API никогда не должен иметь “типизированных” ресурсов, которые являются значимыми для клиента. Авторы спецификаций могут использовать типы ресурсов для описания реализации сервера, скрытой за интерфейсом, но эти типы должны быть иреллевантными и прозрачными для клиента. Единственными типами, которые имеют значение для клиента, должны быть media-тип текушего представления и стандартизованные имена отношений. [*Аналогично*]
* REST API должен вводиться без предварительных знаний кроме начального URI (закладки) и набора стандартизированных media-типов, которые подходят для целевой аудитории (то есть будут правильно поняты любым клиентом, который мог бы использовать этот API). С этого момента все переходы приложения между состояниями должны основываться на выборе клиентом из предоставленных сервером вариантов, которые или присутствуют в полученных представлениях, или выводятся исходя из пользовательских манипуляций с этими представлениями. Переходы могут быть определены (или ограничены) знаниями клиента о media-типах и механизмах межресурсной связи, причем оба могут быть улучшены на лету (например, за счёт загрузки кода с сервера). [*Ошибка вытекает из того, что движком взаимодействия является внеполосная информация, а не гипертекст[^4].*]
Вероятно, я забыл привести здесь и другие правила, но выше приведены те, которые чаще всего нарушаются в так называемых REST API. Пожалуйста, попробуйте их придерживаться или выберите другой баззворд для своего API.
[^1]: Будучи введенным в [начальный стандарт HTTP 1.1](http://tools.ietf.org/html/rfc2068#section-19.6.2.4), заголовок Link был удален из финальной версии стандарта, но затем вернулся с дополнениями в виде [RFC 5988](http://greenbytes.de/tech/webdav/rfc5988.html).
[^2]: В целом, [GitHub](https://developer.github.com/v3/media/) может проиллюстрировать применение media-типов в API
[^3]: Например, захардкоженные в клиенте предположения что по отдельно взятому URI всегда будет возвращаться объект товара.
[^4]: Любое представление информации с перекрестными ссылками, где пользователь (или машина) может получить выбор на счет дальнейших действий, является гипертекстом. Гипермедиа - это просто расширение гипертекста, которое позвляет включать мультмедиа; по словам Роя Филдинга, большинство исследователей отбросило это различие.