RESTful API час виявлення / дизайн клієнта HATEOAS

Для запуску SaaS, в якому я беру участь, я будую як веб-API RESTful, так і кілька клієнтських програм на різних платформах, які його споживають. Я думаю, що я зрозумів API, але зараз я звертаюся до клієнтів. Коли я читав про REST, я бачу, що ключовою частиною REST є відкриття , але, здається, існує багато суперечок між двома різними трактуваннями того, що насправді означає відкриття:

1. Виявлення розробника : розробник кодує велику кількість деталей API у клієнт, таких як URI ресурсу, параметри запиту, підтримувані методи HTTP та інші деталі, які вони виявили під час перегляду документів та експериментів з відповідями API. Цей тип виявлення IMHO вимагає крутого зв’язування та питання версії API, а також призводить до жорсткого зв’язку коду клієнта з API. Не набагато краще, ніж при використанні добре задокументованої колекції RPC, здається.

2. Виявлення середовища виконання - Клієнтський додаток сам може зрозуміти все, що йому потрібно, з невеликою кількістю інформації, що не входить до діапазону, або взагалі без неї (можливо, лише знання про типи носіїв, з якими API працює). Але для того, щоб зробити API дуже ефективним, здається, потрібно багато шаблонів посилань для параметрів запиту, що змушує інформацію про позасмугову мережу повертатися назад. Можливо, існують інші труднощі, про які я ще не думав, оскільки ще не дійшов до цієї точки розвитку. Але мені подобається ідея вільного зчеплення.

Виявлення часу роботи, здається, є святим Граалем REST, але я бачу дорогоцінну дискусію про те, як реалізувати такого клієнта. Майже всі джерела REST, які я знайшов, припускають відкриття розробника. Хтось знає про деякі ресурси пошуку під час виконання? Кращі практики? Приклади чи бібліотеки з реальним кодом? Я працюю в PHP (Zend Framework) для одного клієнта. Objective-C (iOS) для іншого.

Чи є реалізація Runtime реальною метою, враховуючи наявний набір інструментів та знань у спільноті розробників? Я можу написати своєму клієнту, щоб він непрозоро обробляв усі URI, але як це зробити найефективніше - це питання, особливо щодо низькосмугових з’єднань. У будь-якому випадку, URI - це лише частина рівняння. А як щодо шаблонування посилань у контексті виконання? Як щодо того, щоб повідомити, які методи підтримуються, крім того, щоб зробити багато запитів OPTIONS?

Це, безумовно, міцний горіх. У Google ми впровадили нашу службу Discovery, на якій створені всі наші нові API. Версія TL; DR - це те, що ми генеруємо специфікацію, схожу на схему JSON, яку наші клієнти можуть аналізувати - багато з них динамічно.

Ці результати означають простіші оновлення SDK для розробника та легше / краще обслуговування для нас.

Це далеко не ідеальне рішення, але багатьом нашим розробникам, здається, подобається.

Детальніше див. У посиланні (і обов’язково перегляньте відео.)

Захоплююче. Те, що ви описуєте, в основному є принципом HATEOAS. Що таке HATEOAS ви запитаєте? Прочитайте це: http://en.wikipedia.org/wiki/HATEOAS

Якщо говорити неспеціалістично, HATEOAS означає посилання, яке слід. Цей підхід відокремлює вашого клієнта від конкретних URL-адрес і дає вам можливість змінювати свій API, не порушуючи нікого.

Ви зробили домашню роботу і досягли суті її: відкриття часу - це святий Грааль. Не переслідуйте це.

UDDI розповідає гостру історію відкриття середовища виконання: http://en.wikipedia.org/wiki/Universal_Description_Discovery_and_Integration

Однією з вимог, яку слід виконати, перш ніж ви можете викликати API 'RESTful', є те, що поверх цього API має бути можливість написати загальний клієнтський додаток. За допомогою загального клієнта користувач повинен мати доступ до усіх функціональних можливостей API. Універсальний клієнт - це клієнтська програма, яка не припускає, що будь-який ресурс має певну структуру, яка перевищує структуру, визначену типом носія. Наприклад, веб-браузер - це загальний клієнт, який знає, як інтерпретувати HTML, включаючи HTML-форми тощо.

Тепер, припустимо, у нас є HTTP / JSON API для веб-магазину, і ми хочемо створити клієнт HTML / CSS / JavaScript, який надає нашим клієнтам чудовий досвід користування. Чи було б реалістичним варіантом дозволити цьому клієнту бути загальним клієнтським додатком? Ні. Ми хочемо надати певний зовнішній вигляд для кожного конкретного елемента даних та кожного конкретного стану програми. Ми не хочемо включати всі знання про ці особливості презентації в API, навпаки, клієнт повинен визначити зовнішній вигляд, а API повинен нести лише дані. Це означає, що клієнт має жорстко закодовану зв'язок конкретних елементів ресурсу з конкретними макетами та взаємодіями користувачів.

Це кінець HATEOAS і, отже, кінець REST? так і ні .

Так , оскільки, якщо ми жорстко кодуємо знання про API в клієнт, ми втрачаємо переваги HATEOAS: зміни на стороні сервера можуть зламати клієнта.

Ні , з двох причин:

1. Бути "RESTful" - це властивість API, а не клієнта. Поки теоретично можливо створити загальний клієнт, який пропонує всі можливості API, API можна назвати RESTful. Той факт, що клієнти не дотримуються правил, не є виною API. Той факт, що загальний клієнт мав би погану взаємодію з користувачем, не є проблемою. Чому важливо знати, що можна мати загального клієнта, якщо у нас насправді цього загального клієнта немає? Це підводить мене до другої причини:
2. API RESTful пропонує клієнтам можливість вибрати, наскільки загальними вони хочуть бути, тобто наскільки стійкими до змін на стороні сервера вони хочуть бути. Клієнти, яким потрібно забезпечити чудову взаємодію з користувачами, все ще можуть бути стійкими до змін URI, змін значень за замовчуванням тощо. Клієнти, які виконують пакетні роботи без взаємодії з користувачем, можуть бути стійкими до інших видів змін.

Якщо вас цікавлять практичні приклади, перегляньте мій документ JAREST . Останній розділ - про HATEOAS. Ви побачите, що за допомогою JAREST навіть високоінтерактивні та візуально привабливі клієнти можуть бути досить стійкими до змін на стороні сервера, хоча і не на 100%.

Я думаю, що важливим моментом щодо HATEOAS є не те, що це якась сторона клієнта святого Грааля, а те, що він ізолює клієнта від змін URI - передбачається, що ви використовуєте відомі (або виявлені користувачем розроблені) Відносини посилань, які дозволять системі знати, яке посилання на об’єкт є формою, яку можна редагувати. Важливим моментом є використання типу emdia, який усвідомлює гіпермедіа (наприклад, HTML, XHTML тощо).

Ви пишете:

Щоб зробити API дуже ефективним, здається, потрібно багато шаблонів посилань для параметрів запиту, що змушує зворотну інформацію проникати назад.

Якщо цей шаблон посилання наведено в попередньому запиті, інформація про позасмугове відсутнє. Наприклад, HTML-форма пошуку використовує шаблонування посилань ( /search?q=%@) для створення URL-адреси ( /search?q=hateoas), але клієнт (веб-браузер) не знає нічого, крім того, як використовувати HTML-форми та GET.