Является ли этот REST API Действительно RPC?Рой Филдинг , похоже , думает именно так
https://stackoverflow.com/questions/1164154
italiano
english
français
española
中国
日本の
العربية
Deutsch
한국어
Português
RussianВопрос
Большая часть того, что, как мне казалось, я знал о REST, очевидно, неверна - и я не одинок.Этот вопрос имеет длинный ввод, но он кажется необходимым, потому что информация немного разрозненна.Собственно, вопрос задан в конце, если вы уже знакомы с этой темой.
Из первого абзаца книги Роя Филдинга REST API должны управляться гипертекстом, совершенно очевидно, что он считает, что его работа широко неверно истолковывается:
Меня расстраивает количество людей, называющих любой интерфейс на основе HTTP REST API.Сегодняшний пример - это REST API социального сайта.Это и есть RPC.Это кричит RPC.На дисплее так много сцепления, что ему следует присвоить оценку X.
Филдинг продолжает перечислять несколько атрибутов REST API.Некоторые из них, похоже, идут вразрез как с общепринятой практикой, так и с распространенными советами на SO и других форумах.Например:
REST API следует вводить без каких-либо предварительных знаний, кроме начального URI (закладки) и набора стандартизированных типов мультимедиа, которые подходят для целевой аудитории (т. Е. должны быть поняты любым клиентом, который может использовать API)....
REST API не должен определять фиксированные имена ресурсов или иерархии (очевидная связь клиента и сервера)....
REST API должен тратить почти все свои описательные усилия на определение типов носителей, используемых для представления ресурсов и управления состоянием приложения, или на определение расширенных имен связей и / или разметки с поддержкой гипертекста для существующих стандартных типов носителей....
Идея "гипертекста" играет центральную роль - гораздо большую, чем структура URI или значение HTTP-глаголов."Гипертекст" определен в одном из комментариев:
Когда я [Филдинг] говорю "гипертекст", я имею в виду одновременное представление информации и элементов управления таким образом, что информация становится средством, с помощью которого пользователь (или автомат) получает возможность выбора и выбирает действия.Гипермедиа - это всего лишь расширение понятия "текст", подразумевающее включение временных якорей в медиапоток;большинство исследователей отказались от этого различия.
Гипертекст не обязательно должен быть HTML в браузере.Компьютеры могут переходить по ссылкам, когда они понимают формат данных и типы связей.
На данный момент я предполагаю, но первые два пункта выше, похоже, предполагают, что документация API для ресурса Foo, которая выглядит следующим образом, приводит к тесной связи между клиентом и сервером и не имеет места в RESTful системе.
GET /foos/{id} # read a Foo
POST /foos/{id} # create a Foo
PUT /foos/{id} # update a Foo
Вместо этого агент должен быть вынужден обнаруживать URI для всех Foo, например, отправляя запрос GET для /foos .(Возможно, окажется, что эти URI соответствуют приведенному выше шаблону, но это не относится к делу.) В ответе используется тип носителя, который способен передать, как получить доступ к каждому элементу и что с ним можно сделать, что приводит к третьему пункту выше.По этой причине документация API должна быть сосредоточена на объяснении того, как интерпретировать гипертекст, содержащийся в ответе.
Более того, каждый раз, когда запрашивается URI для ресурса Foo, ответ содержит всю информацию, необходимую агенту для определения дальнейших действий, например, путем доступа к связанным и родительским ресурсам через их URI или путем принятия мер после создания / удаления ресурса.
Ключом ко всей системе является то, что ответ состоит из гипертекста, содержащегося в типе носителя, который сам передает агенту варианты продолжения.Это мало чем отличается от того, как браузер работает для людей.
Но это всего лишь мое лучшее предположение на данный конкретный момент.
Филдинг опубликовал последующие меры в котором он ответил на критику за то, что его обсуждение было слишком абстрактным, не хватало примеров и изобиловало жаргонизмом:
Другие попытаются расшифровать то, что я написал, таким образом, чтобы это было более прямолинейно или применимо к какой-либо практической проблеме сегодняшнего дня.Вероятно, я этого не сделаю, потому что я слишком занят работой над следующей темой, подготовкой к конференции, написанием очередного стандарта, поездкой в какое-нибудь отдаленное место или просто выполнением мелочей, которые позволяют мне чувствовать, что я заработал свою зарплату.
Итак, два простых вопроса к ОСТАЛЬНЫМ экспертам с практическим складом ума:как вы интерпретируете то, что говорит Филдинг, и как вы применяете это на практике при документировании / внедрении REST API?
Редактировать:этот вопрос - пример того, как трудно может быть чему-то научиться, если у вас нет названия для того, о чем вы говорите.Название в данном случае - "Гипермедиа как механизм управления состоянием приложения" (HATEOAS).
Решение
Я думаю, что ваше объяснение в основном охватывает это.URI - это непрозрачные идентификаторы, которые по большей части не должны передаваться за пределы URI закладки, используемого агентом пользователя для доступа к приложению.
Что касается документирования, то этот вопрос задавался довольно много раз.Вы документируете свой тип носителя вместе с содержащимися в нем элементами управления гиперссылками (ссылки и формы) и модель взаимодействия, если хотите (см. AtomPub).
Если вы документируете URI или способы их создания, вы делаете это неправильно.
Другие советы
Ваша интерпретация кажется мне правильной.Я действительно верю, что ограничения Филдинга могут быть применены практически.
Я действительно хотел бы, чтобы кто-нибудь опубликовал несколько хороших примеров того, как документировать интерфейс REST.Есть так много плохих примеров, что было бы очень полезно привести несколько достоверных, на которые можно было бы указать пользователям.
Я искал хороший пример API, написанного после HATEOAS, и у меня возникли проблемы с поиском (я обнаружил, что как SunCloud API, так и AtomPub сложно применить к "нормальной" ситуации с API).Поэтому я попытался создать реалистичный пример в своем блоге, следуя совету Роя Филдинга о том, что значит быть правильной реализацией REST.Мне было очень сложно придумать этот пример, несмотря на то, что в принципе он довольно прост (просто сбивает с толку при работе с API, в отличие от веб-страницы).Я понимаю, с чем Рой был не согласен, и согласен, это просто сдвиг в мышлении для правильной реализации API.
Взгляните-ка: Пример API с использованием Rest
Единственным исключением из инструкции о том, как создавать URI, является то, что допустимо отправлять шаблон URI в гипертекстовом ответе с полями, которые будут автоматически заменяться клиентом, используя другие поля в гипертексте.Обычно это не приводит к значительной экономии полосы пропускания, поскольку сжатие gzip будет обрабатывать повторяющиеся части URI достаточно хорошо, чтобы не беспокоиться об этом.
Несколько хороших дискуссий о REST и связанных с ними HATEOAS:
Для тех, кому интересно, я нашел подробный пример применения HATEOAS на практике в Sun Cloud API - интерфейс Sun Cloud API.
Дело в том, что большинство людей ошибаются в том, что (по крайней мере, я думаю) в мире REST вы не документируете свой "интерфейс Rest", то, что вы документируете, является типом носителя, независимо от вашего сервера или службы.
Абсолютно верно.Кроме того, я хотел бы отметить, что шаблоны URI прекрасно работают в приложении RESTful, если шаблоны взяты из документов, полученных с сервера (подходящим примером является OpenSearch).Для шаблонов URI вы документируете, где они используются и каковы ожидаемые заполнители в шаблоне, но не сами шаблоны.Немного вопреки тому, что сказал Ванфриден, этот случай не является исключением.
Например, на моей работе у нас есть внутренняя система управления доменом, и в сервисном документе указаны два шаблона URI:один для создания URI наилучшего предположения для ресурса домена, а другой для построения URI для запроса доступности домена.Все еще возможно просмотреть коллекцию доменов, чтобы выяснить, каков URI данного домена, но, учитывая огромное количество доменов, которыми он управляет, это было бы невозможно для клиента, поэтому предоставление им способа угадать, каким может быть URI ресурса домена, является огромным выигрышем с точки зрения простоты реализации с точки зрения клиента и пропускной способности с точки зрения сервера.
Перейдем к вашему вопросу:Наша нормативная документация - это открытые ресурсы, влияние различных методов на эти ресурсы, используемые типы носителей представления и их схемы, а также на какие ресурсы указывают URI в этих представлениях.
Мы также включаем ненормативную (информативную) документацию, к которой прилагается отказ от ответственности не вчитываться слишком глубоко в URI, упомянутые в документе, в котором приведены примеры типичных взаимодействий клиент-сервер.Это облекает довольно абстрактную нормативную документацию в конкретные термины.
Я думаю, что за те годы, что REST существует сейчас, технологи смирились с концепцией Ресурса и с тем, что на самом деле является RESTful, а что нет.
Согласно модели зрелости Ричардсона, существует 4 уровня (0-3), которые определяют, насколько RESTful ваш API, причем 3 означает действительно RESTful API, как и предполагал Рой Филдинг.
Уровень 0 - это когда у вас есть одна точка входа, подобная URI SOAP.
Уровень 1 означает, что API способен различать различные ресурсы и имеет более одной точки входа - все еще пахнет МЫЛОМ.
Уровень 2 - это когда вы используете HTTP-глаголы - GET, POST, DELETE в первую очередь.Это тот уровень, на котором ОТДЫХ действительно входит в картину.
На уровне 3 вы начинаете использовать элементы управления гипермедиа для создания своего API воистину Спокойный.
Предлагаемые ссылки для дальнейшего чтения:
Давайте предположим GET /foos/createForm вызывается для получения значений полей формы, для которых должны быть предоставлены, когда мы переходим к созданию POST /foos .Теперь этот конкретный URL, т. е. 1, используемый для создания foo, должен быть упомянут в ответе для GET /foos/createForm в качестве ссылки для отправки действия в соответствии с предложением Филдинга, верно?
Тогда в чем преимущество сопоставления действий с хорошо известными Http-глаголами для действий, "соглашение о коде / конфигурации" аннулируется.
