Велика кількість того, що я думав, що знаю про REST, мабуть, помиляється - і я не один. Це питання має тривалий результат, але, здається, це необхідно, оскільки інформація трохи розсіяна. Справжнє запитання закінчується, якщо ви вже знайомі з цією темою.
З першого абзацу API REST API Роя Філдінга повинен бути орієнтований на гіпертекст , зрозуміло, що він вважає, що його робота широко тлумачиться неправильно:
Мене засмучує кількість людей, які називають будь-який інтерфейс на основі HTTP REST API. Сьогоднішній приклад - API REST SocialSite . Це RPC. Це кричить RPC. На дисплеї стільки з’єднань, що їй слід дати оцінку X.
Філдінг продовжує перераховувати кілька атрибутів API REST. Деякі з них, здається, суперечать як загальній практиці, так і загальним порадам на ПЗ та інших форумах. Наприклад:
API REST слід вводити без попередніх знань понад початковий URI (закладку) та набір стандартизованих типів носіїв, які підходять для передбачуваної аудиторії (тобто очікується, що їх зрозуміє будь-який клієнт, який може використовувати API). ...
API REST не повинен визначати імена фіксованих ресурсів або ієрархії (очевидна зв'язок клієнта і сервера). ...
API REST повинен витратити майже всі свої описові зусилля для визначення типів медіа (ів), які використовуються для представлення ресурсів та керування станом програми, або для визначення розширених імен відношень та / або розмітки з підтримкою гіпертексту для існуючих стандартних типів медіа. ...
Ідея "гіпертексту" відіграє центральну роль - набагато більше, ніж структура URI або те, що означають HTTP дієслова. "Гіпертекст" визначений в одному з коментарів:
Коли я [Філдінг] кажу гіпертекст, я маю на увазі одночасне представлення інформації та керування таким чином, що інформація стає дозволом, завдяки якому користувач (або автомат) отримує вибір і вибирає дії. Hypermedia - це лише розширення того, що означає текст для включення тимчасових якорів у медіапотік; більшість дослідників скинули цю різницю.
Гіпертекст не повинен бути 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?
Редагувати: це питання є прикладом того, як важко щось дізнатися, якщо у вас немає імені для того, про що ви говорите. Назва в цьому випадку - "Гіпермедіа як двигун стану заявки" (HATEOAS).