Поскольку REST - это просто генерация просматриваемой сети Web, которую мы все знаем, вы можете применять те же концепции, что и при внедрении своей системы для браузера.Короче говоря, сервер должен предоставлять клиенту всю необходимую информацию, которая потребуется клиенту для принятия обоснованных решений о том, какие ресурсы будут вызывать следующие.
В веб-приложении на основе браузера модель взаимодействия может быть аналогична вызовуНа стартовой странице вы увидите интересующий вас раздел ответа, нажмите на ссылку, чтобы узнать подробности.На следующей странице могут быть перечислены некоторые элементы, где вам предоставлены дополнительные элементы управления для изменения этого списка, то есть добавить новый элемент, удалить один и так далее.После нажатия какой-либо кнопки «Добавить» вам предоставляется форма, которая сообщает вам, какие поля должен содержать запрос, а также куда следует отправлять этот запрос, даже если он может быть невидим для вас.Сзади браузер позаботится об этом за вас.Прыжок здесь заключается в том, что сервер фактически передает клиенту любую информацию, необходимую для выполнения его задачи, будь то выбор доступных ссылок для изучения или представление некоторых рекомендаций о том, как должен выглядеть запрос.
Чтобы определить, представляет ли ссылка интерес для клиента, сервер будет использовать значимые имена отношений ссылки, «привязанные» к URI, которые клиент должен использовать вместо анализа и интерпретации URI.Это позволяет серверу изменять URI в любое время, не затрагивая клиента.Филдинг упомянул следующее в одном из своих постов:
API-интерфейс REST должен потратить почти все свои описательные усилия на определение типа (ов) медиа, используемых для представления ресурсов и управления состоянием приложения, или на определениерасширенные имена отношений и / или гипертекстовая разметка для существующих стандартных типов носителей.( Источник )
В дополнение к этому API REST не должны иметь типизированных ресурсов , значимых для клиентов, поскольку это в основном тесно связывает клиента с самим APIи приведет к сбоям, если подача когда-либо изменит что-либо в отношении возвращенного ответа.Вместо этого следует использовать согласование типа содержимого, чтобы позволить клиенту и серверу согласовывать фактический используемый формат представления.
Тип носителя определяет правила обработки некоторой полезной нагрузки, получаемой для определенного Content-Type HTTP-заголовка.,Эти правила определяют как синтаксис, так и семантику документа.Таким образом, серверам в архитектуре REST разрешено отклонять любые сообщения, отправленные для определенного типа контента, если правила, указанные в типе носителя, нарушены .
Несмотря на то, что акцент на типах носителей не препятствует изменениям, вносимым в полностью полученные представления, он все же полезен для дальнейшего разделения клиентов с серверов и сокращения внеполосной информации, необходимой для взаимодействия.с обслуживанием.Вместо того, чтобы связывать клиента напрямую с API, оба фактически связаны с типом медиа, и может быть несколько типов медиа, с которыми они фактически связаны.Если когда-либо понадобится изменить тип носителя, вы можете легко ввести новый тип носителя или, подобно HTML, указать в типе носителя, как достигается обратная совместимость.
Относительно предыдущих требований внешней информации, которые REST не удаляет полностью, Филдинг заявил:
Конечно, клиент имеет предварительные знания.Каждый протокол, каждое определение типа мультимедиа, каждая схема URI и каждый тип отношения ссылки составляют предварительное знание, которое клиент должен знать (или изучать), чтобы использовать это знание.ОТДЫХ не устраняет необходимость в подсказке.Что REST делает, так это концентрирует потребность в предварительных знаниях в легко стандартизированных формах.Это существенное различие между ориентированной на данные и ориентированной на управление интеграцией.( Источник )
Поскольку REST не фокусируется на одном-единственном аспекте, а представляет собой совокупность всех аспектов, упомянутых выше, ваш актуальный вопрос должен решаться с разных точек зрения.
Во-первых, либо используйте существующие связи, т.е. IANA или другими микроформатами , определите новые, которые в лучшем случае следует зарегистрировать в IANA, или используйте некоторые теги, связанные с семантической сетью, такие как schema.org .То есть, если у вас есть коллекции, то next, prev, first и last являются довольно значимыми (и уже зарегистрированы в IANA) для нумерации страниц или item для обязательного элемента в списке.Эта коллекция могла быть возвращена ранее как collection ранее или указана соответствующим элементом, чтобы вернуться к предыдущей коллекции.Если что-то вроде добавления или редактирования должно быть выполнено, ссылка-отношение типа edit-form может научить клиента, что URI вернет какую-то форму, которая сообщит клиенту, как должен выглядеть запрос к API.
Далее, поскольку базовый JSON не так уж хорош с точки зрения предоставления помощи клиенту, так как все, что он делает, это определяет синтаксическую структуру документа, но не поддерживает определенные элементы, что означает, что некоторые более продвинутые типы носителей должныбыть поддержанным.Как уже упоминалось Cassio и Exadra37, существует несколько типов документов на основе JSON, которые обеспечивают поддержку HATEOAS (~ URI и имена отношений ссылок).Вместо того, чтобы идти только на то есть application/hal+json, было бы предпочтительным множество типов документов, так как это просто увеличивает совместимость с множеством разных клиентов, которые могут поставляться с поддержкой других типов носителей.Обратите внимание, что нет ничего плохого и в возврате HTML-представления.REST не ограничивает вас только определенным содержимым JSON или XML.Я полагаю, что большую часть времени вместо указания собственного типа мультимедиа было бы достаточно просто использовать HTML для передачи значения контента от API к серверу.
Вы, конечно, можете создавать свои собственные медиавведите и используйте его.Однако для повышения совместимости вы должны стандартизировать его и, возможно, также предоставить плагины / библиотеки для сторонних платформ, чтобы они также могли использовать ваш формат.
Хотя лучший совет, конечно, это повторное использованиеСуществующие стандарты, так как вероятность того, что другие клиенты уже знакомы с такими реализациями или концепциями, намного выше, чем для вашего пользовательского формата.Кроме того, это, вероятно, также избавляет вас от большой работы и усилий.