WADL (Web Application Description Language)

Материал из Национальной библиотеки им. Н. Э. Баумана
Последнее изменение этой страницы: 13:57, 24 декабря 2016.
Версия от 13:57, 24 декабря 2016; andrey nikolaev (обсуждение | вклад) (Опция)

(разн.) ← Предыдущая | Текущая версия (разн.) | Следующая → (разн.)

WADL (англ. Web Application Description Language) - машиноориентированное XML представление веб-сервисов, основанных на HTTP. WADL предназначена для упрощения повторного использования веб-сервисов, которые основаны на существующем HTTP архитектуре Web. WADL платформо- и языконезависимое представление, направленное на содействие повторному использованию приложений за пределами основной области использования в веб-браузере. WADL был представлен консорциуму World Wide Web американской компанией Sun Microsystems 31 августа 2009 г., но консорциум не имеет текущих планов по стандартизации его. WADL является REST эквивалентом SOAP Web Services Description Language (WSDL), который также может быть использован для описания REST веб-служб.

Формат

Сервис описывается с помощью набора элементов ресурсов. Каждый ресурс содержит элементы параметров для описания входных данных и элементы методов, описывающие запрос и ответ ресурса. Элемент запроса определяет , как представлять входные данные , какие типы необходимы и какие конкретные HTTP заголовки необходимы. Элемент ответа описывает представление ответа сервиса, а также любую информацию о неисправности, давая возможность взаимодействовать с ошибками.

Ресурс

Элемент resource описывает набор ресурсов, каждый из которых определяется URI, который следует образцу. Элемент resource имеет следующие атрибуты:

  • id. Необязательный атрибут типа XSD: ID, который идентифицирует элемент ресурса.
  • path. Необязательный атрибут типа XSD: строка. Если он присутствует, он обеспечивает относительный шаблон URI для идентификатора ресурса. База ресурса URI задается ресурсом элемента ресурса родительского элемента.
  • type.Необязательный атрибут тип которого является разделенный пробелами список из XSD: anyURI. Каждое значение в списке является перекрестной ссылкой, которая идентифицирует элемент resource_type, который определяет набор методов, поддерживаемых ресурсом.
  • queryType.Определяет тип носителя для компонента запроса ресурса URI.

Элемент resource содержит следующие дочерние элементы:

  • template. Предоставляет дополнительную информацию о вложенном параметре шаблона. Элементы param ребенка, имя значение атрибута которых не совпадает с именем вложенного шаблона параметра игнорируются.
  • matrix. Определяет матричный параметр URI
  • query. Задает глобальный параметр запроса URI для всех дочерних элементов method ресурса. Не относится к методам , наследуемых от resource_type и заданных с помощью атрибута type .
  • header. Задает глобальный HTTP заголовок для использования в части запроса всех дочерних элементов methods ресурса. Не относится к методам , наследуемых от resource_type и заданных с помощью атрибута type .
 
  <resource path="widgets/{widgetId}">  
    <param name="widgetId" style="template" type="xsd:int"/>  
    ...  
  </resource>

Следующий пример показывает отрывок из описания веб-приложения, которое предоставляет несколько ресурсов:

 
 <resources base="http://example.com/">  
   <resource path="widgets">  
     <resource path="reports/stock">  
       <param name="instockonly" style="matrix"  
         type="xsd:boolean"/>  
       ...  
     </resource>  
    <resource path="{widgetId}">  
       ...  
     </resource>  
     ...  
   </resource>  
   <resource path="accounts/{accountId}">  
     ...  
   </resource>  
 </resources>

Тип ресурса

Элемент resource_type описывает набор методов , которые вместе определяют поведение типа ресурса. Элемент resource_type Может быть использован для определения поведения ресурса , который , как ожидается, будет поддерживаться несколькими ресурсами. Элемент resource_type имеет следующие атрибуты:

  • id. Обязательный атрибут типа XSD: ID, который идентифицирует элемент resource_type.

Метод

Элемент method описывает вход и выход из метода протокола HTTP , который может быть применен к ресурсу. Элемент method может представлять собой либо определение метода либо ссылку на метод , определенный в другом месте. Опорный элемент method является дочерним элементом элемента resource , который имеет атрибут href , тип которого xsd:anyURI. Значение атрибута href является перекрестной ссылки к элементу method. Опорный элемент method не должен иметь каких - либо других WADL определенных атрибутов или содержать WADL определенные дочерние элементы.

Элемент определения method является дочерним элементом элемента resource или элемента application и имеет следующие атрибуты:

  • name. Указывает метод HTTP, который используется.
  • id. Идентификатор метода, необходимый для глобально определенных методов, не допускаются на местном уровне встроенных методов. Методы идентифицируются XML ID и называются с использованием ссылки URI.

Допустимо иметь несколько дочерних элементов method , которые имеют одинаковое значение атрибута name для данного ресурса; такие братья представляют различные вариации одного и того же метода HTTP и, как правило , имеют различные входные данные.

Элемент method имеет следующие дочерние элементы:

  • doc. Ноль или более элементов doc.
  • request. Описывает вход метода как совокупность параметров и опционального представления ресурса.
  • response. Ноль или более элементов response , которые описывают возможные результаты метода

Запрос

Элемент request описывает вход для включения при применении метода HTTP к ресурсу. Элемент request не имеет атрибутов и может содержать следующие дочерние элементы:

  • Ноль или более элементов doc
  • Ноль или более элементов representation
  • Ноль или более элементов param

Следующий пример показывает ресурс с порождающей URI, который поддерживает единственный метод HTTP с двумя дополнительными параметрами запроса:

 
 <resources base="http://example.com/widgets">  
   <resource path="{widgetId}">  
     <param name="customerId" style="query"/>  
     <method name="GET">  
       <request>  
         <param name="verbose" style="query" type="xsd:boolean"/>  
       </request>  
       <response>  
         ...  
       </response>  
     </method>  
   </resource>  
 </resources>

Ответ

Элемент response описывает вывод, полученного в результате выполнения метода HTTP на ресурсе. Она имеет следующие атрибуты:

  • status. Дополнительно присутствует на ответах, предоставляет список кодов состояния HTTP, связанные с конкретным ответом.

Элемент response может содержать следующие дочерние элементы:

  • Ноль или более элементов doc
  • Ноль или более элементов representation, каждый из которых описывает представления ресурса , которые могут возникнуть в результате реализации способа. Родственные элементы representation указывают на логически эквивалентные альтернативы; нормальные механизмы согласования контента HTTP могут быть использованы для выбора конкретной альтернативы.
  • Ноль или более элементов param со значением 'заголовка' для их атрибута style , каждый из которых определяет детали заголовка HTTP для ответа

Опция

Элемент option определяет один из множества возможных значений параметра , представленного его родительского элемента param .Элемент option имеет следующие атрибуты:

  • value. Обязательный атрибут, который определяет одно из возможных значений родительского параметра.
  • mediaType. Когда присутствует, это указывает на то, что родительский параметр действует как селектор типа носителя для ответов. Значением атрибута является тип носителя , который указан в атрибуте value.

В следующем примере показан способ ресурса с параметром запроса, который может быть использован для запроса определенного формата ответа:

 
<method name="GET">  
   <request>  
     <param name="format" style="query">  
       <option value="xml" mediaType="application/xml"/>  
       <option value="json" mediaType="application/json"/>  
     </param>  
     ...  
   </request>  
   <response>  
     <representation mediaType="application/xml"/>  
     <representation mediaType="application/json"/>  
   </response>  
 </method>

Пример

В приведенном ниже листинге показан пример описания WADL для приложения Yahoo News Search.

 <application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:schemaLocation="http://wadl.dev.java.net/2009/02 wadl.xsd" 
  xmlns:tns="urn:yahoo:yn" 
  xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
  xmlns:yn="urn:yahoo:yn" 
  xmlns:ya="urn:yahoo:api" 
  xmlns="http://wadl.dev.java.net/2009/02"> 
   <grammars> 
     <include 
       href="NewsSearchResponse.xsd"/> 
     <include 
       href="Error.xsd"/> 
   </grammars> 
 
   <resources base="http://api.search.yahoo.com/NewsSearchService/V1/"> 
     <resource path="newsSearch"> 
       <method name="GET" id="search"> 
         <request> 
           <param name="appid" type="xsd:string" 
             style="query" required="true"/> 
           <param name="query" type="xsd:string" 
             style="query" required="true"/> 
           <param name="type" style="query" default="all"> 
             <option value="all"/> 
             <option value="any"/> 
             <option value="phrase"/> 
           </param> 
           <param name="results" style="query" type="xsd:int" default="10"/> 
           <param name="start" style="query" type="xsd:int" default="1"/> 
           <param name="sort" style="query" default="rank"> 
             <option value="rank"/> 
             <option value="date"/> 
           </param> 
           <param name="language" style="query" type="xsd:string"/> 
         </request> 
         <response status="200"> 
           <representation mediaType="application/xml" 
             element="yn:ResultSet"/> 
         </response> 
         <response status="400"> 
           <representation mediaType="application/xml" 
             element="ya:Error"/> 
         </response> 
       </method> 
     </resource> 
   </resources>
 </application>

Источники