Должен ли я использовать WADL для описания моего RESTful API?

Я собираюсь начать проект, который широко использует подход RESTful. То есть он использует 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-Addressing и WS-Security. Термин «веб-службы REST» обычно относится к архитектуре веб-служб на основе ресурсов, в которой используются HTTP и XML. Каждый из этих архитектурных стилей Web-сервисов имеет свое место, но до недавнего времени стандарт WSDL не в равной степени поддерживал оба стиля. HTTP-привязка WSDL 1.1 была недостаточной для описания взаимодействия с HTTP и XML, поэтому формально описать Web-сервисы REST с помощью WSDL не было. Публикация WSDL 2.0, которая была разработана с учетом Web-сервисов REST, как рекомендация Консорциума World Wide Web (W3C), означает, что теперь существует язык для описания Web-сервисов REST.