Является ли это REST API действительно RPC? Рой Филдинг, кажется, так думает

Большое количество того, что я думал о REST, по-видимому, ошибочно, и я не одинок. Этот вопрос имеет длинный ввод, но он кажется необходимым, потому что информация немного разбросана. Фактический вопрос приходит к концу, если вы уже знакомы с этой темой.

Из первого абзаца Roy Fielding API REST должен быть основан на гипертексте, это довольно ясно, он считает, что его работа широко неверно истолкована:

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

Фильтрация продолжает перечислять несколько атрибутов REST API. Некоторые из них, похоже, противоречат как обычной практике, так и общим советам на SO и других форумах. Например:

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

Идея "гипертекста" играет центральную роль - гораздо больше, чем структура URI или то, что означают HTTP-глаголы. "Hypertext" определен в одном из комментариев:

Когда я [Fielding] говорит гипертекст, я имею в виду одновременное представление информации и элементов управления, так что информация становится доступной, благодаря которой пользователь (или автомат) получает выбор и выбирает действия. Hypermedia - это просто расширение, на котором текст означает включение временных якорей в медиа-поток; большинство исследователей отказались от различия.

Hypertext не обязательно должен быть HTML в браузере. Машины могут следовать ссылкам, когда они понимают формат данных и типы отношений.

Я предполагаю, что на данный момент, но в первых двух пунктах, похоже, предполагается, что документация API для ресурса Foo, которая выглядит следующим образом, ведет к плотной связи между клиентом и сервером и не имеет места в системе RESTful.

GET   /foos/{id}  # read a Foo
POST  /foos/{id}  # create a Foo
PUT   /foos/{id}  # update a Foo

Вместо этого агент должен быть вынужден обнаруживать URI для всех Foos, например, выдавая запрос GET на /foos. (Эти URI могут оказаться в соответствии с вышеприведенным рисунком, но это касается точки.) Ответ использует тип носителя, который способен передавать доступ к каждому элементу и что можно сделать с ним, что приводит к возникновению третьей точки выше, По этой причине документация API должна быть сосредоточена на объяснении того, как интерпретировать гипертекст, содержащийся в ответе.

Кроме того, каждый раз, когда запрашивается URI для ресурса Foo, ответ содержит всю информацию, необходимую агенту для обнаружения того, как действовать, например, путем доступа к связанным и родительским ресурсам через их URI или путем принятия мер после создания/удаления ресурса.

Ключ всей системы состоит в том, что ответ состоит из гипертекста, содержащегося в типе носителя, который сам передает в параметры агента для продолжения. Это не похоже на то, как браузер работает для людей.

Но это только мое лучшее предположение в этот конкретный момент.

Филдинг опубликовал продолжение, в котором он ответил на критику, что его дискуссия была слишком абстрактной, отсутствовала в примерах и богата жаргоном:

Другие попытаются расшифровать то, что я написал, более прямолинейными или применимыми к некоторым практическим проблемам сегодняшнего дня. Я, вероятно, не буду, потому что я слишком занят борьбой со следующей темой, подготовкой к конференции, написанием другого стандарта, поездкой в какое-то отдаленное место или просто выполнением мелочей, которые позволяют мне чувствовать, что я заслужил свою зарплату.

Итак, два простых вопроса для экспертов REST там с практическим мышлением: как вы интерпретируете то, что говорит Филдинг, и как вы применяете его на практике при документировании/реализации API REST?

Изменить: этот вопрос является примером того, как трудно научиться чему-то, если у вас нет имени того, о чем вы говорите. В этом случае именем называется "Hypermedia as Engine of Application State" (HATEOAS).

Ответ 1

Я думаю, что ваше объяснение в основном охватывает его. URI являются непрозрачными идентификаторами, которые по большей части не должны передаваться за пределы URI закладки, которые пользовательский агент использует для доступа к приложению.

Что касается документирования, этот вопрос был сделан довольно много раз. Вы документируете свой тип носителя вместе с элементами управления гиперссылкой, которые он содержит (ссылки и формы), и модель взаимодействия, если вы этого пожелаете (см. AtomPub).

Если вы документируете URI или как их создавать, вы делаете это неправильно.

Ответ 2

Ваша интерпретация кажется мне верной. Я действительно считаю, что ограничения Fielding могут быть практически применены.

Мне действительно хотелось бы, чтобы кто-то опубликовал несколько хороших примеров того, как документировать интерфейс REST. Существует так много плохих примеров, что некоторые из них могут быть полезными для пользователей.

Ответ 3

Я искал хороший пример API, написанный после HATEOAS, и мне не удалось найти его (я обнаружил, что API SunCloud API и AtomPub трудно применить к "нормальной" ситуации API). Поэтому я попытался сделать реалистичный пример в своем блоге, который последовал за советом Роя Филдинга о том, что значит быть надлежащей реализацией REST. Мне было очень сложно придумать пример, несмотря на то, что он довольно прост в принципе (просто запутанный при работе с API, а не с веб-страницей). Я получаю то, что Рой принимал с собой и согласен, это просто сдвиг в мышлении для правильной реализации API.

Посмотрите: Пример API с использованием Rest

Ответ 4

Единственное исключение для предоставления инструкции о том, как создавать URI, заключается в том, что разрешено отправлять шаблон URI в гипертекстовом ответе, причем поля автоматически подставляются клиентом, используя другие поля в гипертексте. Обычно это не приводит к экономии полосы пропускания, поскольку, поскольку сжатие gzip будет обрабатывать повторяющиеся части URI достаточно хорошо, чтобы не беспокоиться об этом.

Некоторые хорошие дискуссии по REST и связанным с ними HATEOAS:

Преимущества (также) Использование HATEOAS в API RESTFul

Как получить чашку кофе

Ответ 5

Для тех, кто интересуется, я нашел подробный пример HATEOAS на практике в Sun Cloud API.

Ответ 6

То, что большинство людей ошибается, заключается в том, что (по крайней мере, я думаю) в мире REST вы не документируете свой "интерфейс отдыха", то, что вы документируете, является типом мультимедиа, независимо от вашего сервера или службы.

Ответ 7

Абсолютно верно. Я хотел бы также отметить, что шаблоны URI отлично подходят в приложении RESTful, если шаблоны получены из документов, полученных с сервера (OpenSearch является подходящим примером). Для шаблонов URI вы документируете, где они используются, и какие ожидаемые заполнители в шаблоне, но не сами шаблоны. Немного противоречив тому, что сказал Вайнфриден, это не исключение.

Например, в моей работе у нас есть система управления внутренним доменом, а в служебном документе указаны два шаблона URI: один для создания URI наилучшего предположения для ресурса домена, а другой для построения URI для запроса доступности домена. По-прежнему можно просмотреть через коллекцию доменов информацию о том, что такое URI для данного домена, но с учетом огромного количества доменов, которыми он управляет, это было бы невыполнимо для клиента, поэтому дать им способ угадать, что URI ресурса домена может быть огромной победой с точки зрения простоты реализации с точки зрения клиента и пропускной способностью с сервера.

На ваш вопрос: наша нормативная документация раскрывает ресурсы, влияние различных методов на эти ресурсы и используемые типы медиаресурсов представления и их схемы, а также какие ресурсы имеют URI в этих представлениях.

Мы также включаем ненормативную (информативную) документацию, которая прилагает к ней отказ от чрезмерного чтения в URI, упомянутый в документе, в котором приводятся примеры типичных взаимодействий клиент-сервер. Это дает довольно абстрактную нормативную документацию в конкретных терминах.

Ответ 8

Я думаю, что за те годы, что REST был там сейчас, технологи пришли к соглашению с концепцией ресурса и тем, что на самом деле является или не является RESTful.

Согласно модели зрелости Ричардсона, существует 4 уровня (0-3), которые определяют, как RESTful ваш API, причем 3 означает действительно RESTful API, как это предполагал Рой Филдинг.

Уровень 0 - это когда у вас есть один URI точки входа - как SOAP.

Уровень 1 означает, что API способен различать разные ресурсы и имеет более чем одну точку входа - все еще пахнет SOAP.

Уровень 2 - это когда вы используете HTTP-глаголы - GET, POST, DELETE в первую очередь. Это уровень, на котором REST действительно входит в картину.

На уровне 3 вы начинаете использовать средства управления гипермедиами, чтобы сделать ваш API действительно RESTful.

Рекомендуемые ссылки для дальнейшего чтения:

Ответ 9

Предположим, что GET /foos/createForm вызывается для получения значений полей формы, которые должны быть предоставлены при создании POST /foos. Теперь этот конкретный URL-адрес, например, 1, используемый для создания foos, должен быть указан в ответе для GET /foos/createForm в качестве ссылки действия отправки в соответствии с предложением Fielding, правильно?
Тогда в чем преимущество сопоставления действий с известными глаголами Http для действий," соглашение над кодом /config " вещь аннулируется.