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

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

I am getting frustrated by the number of people calling any HTTP-based interface a REST API. Today’s example is the SocialSite REST API. That is RPC. It screams RPC. There is so much coupling on display that it should be given an X rating.

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

A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). ...

A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). ...

A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types. ...

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

When I [Fielding] say hypertext, I mean the simultaneous presentation of information and controls such that the information becomes the affordance through which the user (or automaton) obtains choices and selects actions. Hypermedia is just an expansion on what text means to include temporal anchors within a media stream; most researchers have dropped the distinction.

Hypertext does not need to be HTML on a browser. Machines can follow links when they understand the data format and relationship types.

Я догадываюсь об этом, но первые два пункта выше, кажется, предполагают, что документация 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 или предпринимая действия после создания / удаление ресурса.

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

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

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

Others will try to decipher what I have written in ways that are more direct or applicable to some practical concern of today. I probably won’t, because I am too busy grappling with the next topic, preparing for a conference, writing another standard, traveling to some distant place, or just doing the little things that let me feel I have I earned my paycheck.

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

Edit: this question is an example of how hard it can be to learn something if you don't have a name for what you're talking about. The name in this case is "Hypermedia as the Engine of Application State" (HATEOAS).