Я собираюсь начать проект, который широко использует подход 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 :
источник