Чи слід використовувати WADL для опису мого API RESTful?

Я збираюся розпочати проект, який широко використовує правильний підхід REST. Тобто, він використовує HATEOAS і обслуговує ресурси таким чином, що дозволяє проводити загальну розвідку клієнтом.

Я хотів би переконатися, що я надаю опис моїх кінцевих точок таким чином, що дозволить клієнтським програмам автоматично генеруватися на широкій кількості мов. Я розумію, що для веб-сервісів на основі SOAP я можу використовувати WSDL і що, очевидно, є WSDL2, який забезпечує більш чітке визначення дієслів HTTP, які використовуються з REST. Однак я бачу, що багато статей хитаються туди-сюди над її корисністю.

Отже, чи варто використовувати WADL, щоб дозволити генераторам зовнішніх кодів швидко створити клієнта для мого веб-додатка чи є кращий стандарт, який очікується?

Моя порада не турбувати. WADL не настільки широко прийнятий. Дивіться це питання щодо переповнення стека, і є кілька переконливих поглядів, що це не дуже добре вписується в такий тип "правильного" REST, який ви описуєте, як показано тут на іншому запитанні про переповнення стека .

Описи WADL займають багато часу для створення (і в основному вручну), і вони додають крихкості, якої HATEOAS призначений для уникнення - тобто у вас будуть чітко визначені точки входу, але саме те, як ваш клієнт переходить, визначається непрозорими посиланнями, а не заздалегідь визначеними 'договір'.

Це не означає, що ви повинні повністю тікати від документації, визначення схеми тощо, хоча це кінець спектру RESTifarian, який би запропонував вам наблизитися до такого високого рівня самоопису, який вам не потрібен. Я не вважав, що це так на практиці. Кілька надійних відпрацьованих прикладів повинні бути усіма незнайомими потребами розробника. І зберіть кілька клієнтів для власного API, щоб спробувати його (досить просто від JQuery). Це дасть вам хороший показник, будуєте ви щось споживаче чи ні.

Хорошим джерелом інформації в цій області є мова додатків гіпертексту . Я вважаю, що це дещо важковаговик, але дебати в списку розсилки є хорошими, актуальними та актуальними.

Сподіваюся, що допоможе вам розпочати роботу.

Стан інтерфейсів REST, керований іншим, окрім інтерактивного браузера, не дуже хороший. HATEOAS - хороший принцип, але він призводить до інтерфейсів, дуже сильно орієнтованих на людей, і це, як правило, призводить до тягаря користувальницького інтерфейсу, який покладається на розробника сервісу (який, як правило, досить зайнятий тим, що сама служба працює).

Сама WADL не надто велика; він насправді не охоплює достатньої кількості семантики служби, щоб зробити можливим інструментальне налаштування. Звичайно, це загалом важка проблема. WSDL рідко виставляє достатню кількість інформації, і для цього докладено набагато більше зусиль (можливо, прикріпити достатню кількість інформації, але навряд чи хтось насправді робить це).

Однак це говорить про те, що мій колега витрачав місяці, працюючи над бібліотекою, яка використовує REST-інтерфейс для сервісу, а описаний WSDL інтерфейс до тієї ж служби ^[*] був автоматично відтворений майже до однакової якості; Решта шляху проходила близько дня написання обгорткового заняття. Моя думка (заснована на обмеженому розмірі вибірки) полягає в тому, що ви не зможете позбутися всієї крихкості в складному сервісі, оскільки семантика служби неминуче розвиватиметься з часом, і що REST краще керувати інтерфейсами для людей, в той час як SOAP краще для бібліотеки інтерфейсів (є хороший інструмент для клієнтів WSDL / SOAP майже для всіх мов примітки). Якщо у вас немає розкоші робити обидва, на кого слід зосередитися, залежатиме від того, який набір клієнтів вам найбільше цікавий.

Я б не доклав великих зусиль до WADL, але якщо ваша REST-рамка створить це для вас (Apache CXF робить це), то немає особливих причин не надавати її. Кожен, хто хоче відключити ваш код, захоче WSDL + SOAP.

^{[*] Як автор відповідної послуги, я можу точно сказати, що обидва інтерфейси підтримували однакові операції - існувала загальна основна абстрактна модель - і в "природному" стилі для обох типів інтерфейсу. З боку сервісу, безумовно, так було, що деякі речі були легшими з REST, а інші - з SOAP.}

W3C зробив офіційну рекомендацію для стандарту REST документації на основі WSDL 2.0 . Ось цитата зі статті IBM :

Термін Веб-сервіси, як правило, асоціюється з послугами на основі операцій або дій, використовуючи SOAP та стандарти WS *, такі як WS-адресація та WS-безпека. Термін веб-сервісів REST, як правило, відноситься до ресурсної архітектури веб-служб, яка використовує HTTP та XML. Кожен із цих архітектурних стилів веб-сервісу має своє місце, але донедавна стандарт WSDL не однаково підтримував обидва стилі. Прив'язка HTTP WSDL 1.1 була недостатньою для опису зв'язку з HTTP та XML, тому формально описати веб-сервіси REST з WSDL не було можливості. Видання WSDL 2.0, розробленого з урахуванням веб-служб REST, як рекомендація Всесвітнього веб-консорціуму (W3C) означає, що тепер існує мова для опису веб-служб REST.