Язык описания службы RESTful
 | В этой статье есть несколько проблем. Пожалуйста, помогите улучшить его или обсудите эти проблемы на странице обсуждения . ( Узнайте, как и когда удалять эти шаблонные сообщения )
|
Язык описания служб RESTful ( RSDL ) — это машиночитаемое XML- описание веб-приложений на основе HTTP (обычно веб-служб REST ). [1]
Язык (определенный Михаилом Пастернаком во время его работы над oVirt RESTful API) позволяет документировать модель ресурсов, предоставляемых службой, отношения между ними, операции и параметры, которые должны быть предоставлены для операций. Он указывает, являются ли параметры обязательными; и описывает возможные перегрузки в виде наборов параметров.
RSDL предназначен для упрощения повторного использования веб-сервисов, основанных на архитектуре Интернета HTTP. Он не зависит от платформы и языка и направлен на содействие повторному использованию приложений, выходящему за рамки базового использования в веб-браузере, как людьми, так и машинами.
В отличие от WADL , он концентрируется на описании URI как автономных точек входа в приложение, которые можно вызывать разными способами, не требуя обход компонентов URI для определения структуры URI и поддержка перегрузок параметров URI/заголовков/тела. Это делает его удобочитаемым и легко воспринимаемым как людьми, так и машинами.
Характеристики
[ редактировать ]- Самоописательно : RSDL представляет различные URI как автономные точки входа в приложение. Следуя URI ресурсов, можно выяснить, какие методы доступны для данных ресурсов и как эти ресурсы можно использовать.
- Машиночитаемый : каждый URI в RSDL содержит всю необходимую информацию для создания из него HTTP-запроса, которую можно легко использовать, получив доступ к внутренним компонентам URI.
- Удобочитаемый : каждый URI в RSDL содержит атрибуты «rel» и «description», описывающие значение данной операции над этим URI. Люди могут легко получить все доступные операции для данной коллекции/ресурса, просто разместив разные дескрипторы в одном URI.
Формат
[ редактировать ]<rsdl rel="rsdl" href="/api?rsdl">
<description />
<version revision="0" build="0" minor="0" major="0" />
<schema rel="schema" href="/api?schema">
<name>api.xsd</name>
<description />
</schema>
<general rel="*" href="/*">
<request>
<headers>
<header required="true|false">
<name />
<description />
<value />
</header>
</headers>
<url>
<parameters_set>
<parameter context="query|matrix" type="xs:string"
required="true|false">
<name />
<value />
</parameter>
</parameters_set>
</url>
</request>
<name />
<description />
</general>
<links>
<link rel="get|..." href="/api/xxx">
<request>
<http_method>GET|POST|PUT|DELETE|...</http_method>
<headers>
<header required="true|false">
<name />
<value />
</header>
</headers>
<url>
<parameters_set>
<parameter context="query|matrix" type=""
required="true|false">
<name />
<value />
</parameter>
</parameters_set>
</url>
<body>
<type>...</type>
<parameters_set>
<parameter type="" required="true|false">
<name>FQ-name-to-parameter</name>
</parameter>
</parameters_set>
</body>
</request>
<response>
<type />
</response>
</link>
</links>
</rsdl>
Компоненты
[ редактировать ]ТИП
[ редактировать ] <links>
<link rel="get|..." href="/api/xxx">
Запрос
[ редактировать ] <request>
<http_method>GET|POST|PUT|DELETE|...</http_method>
<headers>
<header required="true|false">
<name></name>
<value></value>
</header>
...
</headers>
<url>
<parameters_set>
<parameter context="query|matrix" type="" required="true|false">
<name></name>
<value></value>
</parameter>
...
</parameters_set>
...
</url>
<body>
<type>...</type>
<parameters_set>
<parameter type="" required="true|false">
<name>FQ-name-to-parameter</name>
</parameter>
...
</parameters_set>
...
</body>
</request>
Ответ
[ редактировать ] <response>
<type></type>
...
</response>
XML-схема
[ редактировать ] <xs:element name="detailedLinks" type="DetailedLinks"/>
<xs:complexType name="DetailedLinks">
<xs:sequence>
<xs:annotation>
<xs:appinfo>
<jaxb:property name="links"/>
</xs:appinfo>
</xs:annotation>
<xs:element type="DetailedLink" name="link" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:element name="link" type="Link"/>
<xs:complexType name="Link">
<xs:attribute name="href" type="xs:string"/>
<xs:attribute name="rel" type="xs:string"/>
</xs:complexType>
<xs:element name="url" type="Url"/>
<xs:complexType name="Url">
<xs:sequence>
<xs:element ref="parameters_set" maxOccurs="unbounded" minOccurs="0">
<xs:annotation>
<xs:appinfo>
<jaxb:property name="ParametersSets"/>
</xs:appinfo>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:element name="body" type="Body"/>
<xs:complexType name="Body">
<xs:sequence>
<xs:element name="type" type="xs:string" minOccurs="1" maxOccurs="1"/>
<xs:element ref="parameters_set" maxOccurs="unbounded" minOccurs="0">
<xs:annotation>
<xs:appinfo>
<jaxb:property name="ParametersSets"/>
</xs:appinfo>
</xs:annotation>
</xs:element>
</xs:sequence>
<xs:attribute name="required" type="xs:boolean">
<xs:annotation>
<xs:appinfo>
<jaxb:property generateIsSetMethod="false"/>
</xs:appinfo>
</xs:annotation>
</xs:attribute>
</xs:complexType>
<xs:element name="request" type="Request"/>
<xs:complexType name="Request">
<xs:sequence>
<xs:element name="http_method" type="HttpMethod" minOccurs="1" maxOccurs="1"/>
<xs:element ref="headers" minOccurs="0" maxOccurs="1"/>
<xs:element ref="url" minOccurs="0" maxOccurs="1"/>
<xs:element ref="body" minOccurs="0" maxOccurs="1"/>
</xs:sequence>
</xs:complexType>
<xs:simpleType name="HttpMethod">
<xs:restriction base="xs:string">
<xs:enumeration value="GET"/>
<xs:enumeration value="POST"/>
<xs:enumeration value="PUT"/>
<xs:enumeration value="DELETE"/>
<xs:enumeration value="OPTIONS"/>
</xs:restriction>
</xs:simpleType>
<xs:element name="response" type="Response"/>
<xs:complexType name="Response">
<xs:sequence>
<xs:element name="type" type="xs:string" minOccurs="1" maxOccurs="1"/>
</xs:sequence>
</xs:complexType>
<xs:element name="parameter" type="Parameter"/>
<xs:complexType name="Parameter">
<xs:complexContent>
<xs:extension base="BaseResource">
<xs:sequence>
<xs:element name="value" type="xs:string" minOccurs="1" maxOccurs="1"/>
<xs:element ref="parameters_set" minOccurs="0" maxOccurs="1"/>
</xs:sequence>
<xs:attribute name="required" type="xs:boolean">
<xs:annotation>
<xs:appinfo>
<jaxb:property generateIsSetMethod="false"/>
</xs:appinfo>
</xs:annotation>
</xs:attribute>
<xs:attribute name="type" type="xs:string"/>
<xs:attribute name="context" type="xs:string"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:element name="header" type="Header"/>
<xs:complexType name="Header">
<xs:complexContent>
<xs:extension base="BaseResource">
<xs:sequence>
<xs:element name="value" type="xs:string" minOccurs="1" maxOccurs="1"/>
</xs:sequence>
<xs:attribute name="required" type="xs:boolean">
<xs:annotation>
<xs:appinfo>
<jaxb:property generateIsSetMethod="false"/>
</xs:appinfo>
</xs:annotation>
</xs:attribute>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:element name="headers" type="Headers"/>
<xs:complexType name="Headers">
<xs:sequence>
<xs:element ref="header" maxOccurs="unbounded">
<xs:annotation>
<xs:appinfo>
<jaxb:property name="Headers"/>
</xs:appinfo>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:element name="parameters_set" type="ParametersSet"/>
<xs:complexType name="ParametersSet">
<xs:sequence>
<xs:element ref="parameter" maxOccurs="unbounded" minOccurs="0">
<xs:annotation>
<xs:appinfo>
<jaxb:property name="Parameters"/>
</xs:appinfo>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:element name="schema" type="Schema"/>
<xs:complexType name="Schema">
<xs:complexContent>
<xs:extension base="Link">
<xs:sequence>
<xs:element name="name" type="xs:string" minOccurs="0" maxOccurs="1"/>
<xs:element name="description" type="xs:string" minOccurs="0" maxOccurs="1"/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:element name="general_metadata" type="GeneralMetadata"/>
<xs:complexType name="GeneralMetadata">
<xs:complexContent>
<xs:extension base="DetailedLink">
<xs:sequence>
<xs:element name="name" type="xs:string" minOccurs="0" maxOccurs="1"/>
<xs:element name="description" type="xs:string" minOccurs="0" maxOccurs="1"/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:element name="rsdl" type="RSDL"/>
<xs:complexType name="RSDL">
<xs:sequence>
<xs:element name="description" type="xs:string" minOccurs="0"/>
<xs:element type="Version" name="version" minOccurs="0" maxOccurs="1" />
<xs:element ref="schema" minOccurs="0" maxOccurs="1" />
<xs:element type="GeneralMetadata" name="general" minOccurs="0" maxOccurs="1"/>
<xs:element type="DetailedLinks" name="links" minOccurs="0"/>
</xs:sequence>
<xs:attribute name="href" type="xs:string"/>
<xs:attribute name="rel" type="xs:string"/>
</xs:complexType>
Примеры
[ редактировать ]Список ресурсов
[ редактировать ] <link rel="get" href="/api/clusters">
<request>
<http_method>GET</http_method>
<headers>
<header required="false">
<name>Filter</name>
<value>true|false</value>
</header>
</headers>
<url>
<parameters_set>
<parameter context="query" type="xs:string" required="false">
<name>search</name>
<value>search query</value>
</parameter>
<parameter context="matrix" type="xs:boolean" required="false">
<name>case_sensitive</name>
<value>true|false</value>
</parameter>
<parameter context="matrix" type="xs:int" required="false">
<name>max</name>
<value>max results</value>
</parameter>
</parameters_set>
</url>
<body/>
</request>
<response>
<type>Clusters</type>
</response>
</link>
Получить ресурс
[ редактировать ] <link rel="get" href="/api/clusters/{cluster:id}">
<request>
<http_method>GET</http_method>
<headers>
<header required="false">
<name>Filter</name>
<value>true|false</value>
</header>
</headers>
<body/>
</request>
<response>
<type>Cluster</type>
</response>
</link>
Обновить ресурс
[ редактировать ] <link rel="update" href="/api/clusters/{cluster:id}">
<request>
<http_method>PUT</http_method>
<headers>
<header required="true">
<name>Content-Type</name>
<value>application/xml|json</value>
</header>
<header required="false">
<name>Correlation-Id</name>
<value>any string</value>
</header>
</headers>
<body>
<type>Cluster</type>
<parameters_set>
<parameter type="xs:string" required="false">
<name>cluster.name</name>
</parameter>
<parameter type="xs:string" required="false">
<name>cluster.description</name>
</parameter>
<parameter type="xs:string" required="false">
<name>cluster.cpu.id</name>
</parameter>
<parameter type="xs:int" required="false">
<name>cluster.version.major</name>
</parameter>
<parameter type="xs:int" required="false">
<name>cluster.version.minor</name>
</parameter>
<parameter type="xs:double" required="false">
<name>cluster.memory_policy.overcommit.percent</name>
</parameter>
<parameter type="xs:boolean" required="false">
<name>cluster.memory_policy.transparent_hugepages.enabled
</name>
</parameter>
<parameter type="xs:string" required="false">
<name>cluster.scheduling_policy.policy</name>
</parameter>
<parameter type="xs:int" required="false">
<name>cluster.scheduling_policy.thresholds.low</name>
</parameter>
<parameter type="xs:int" required="false">
<name>cluster.scheduling_policy.thresholds.high</name>
</parameter>
<parameter type="xs:int" required="false">
<name>cluster.scheduling_policy.thresholds.duration</name>
</parameter>
<parameter type="xs:string" required="false">
<name>cluster.error_handling.on_error</name>
</parameter>
<parameter type="xs:boolean" required="false">
<name>cluster.virt_service</name>
</parameter>
<parameter type="xs:boolean" required="false">
<name>cluster.gluster_service</name>
</parameter>
<parameter type="xs:boolean" required="false">
<name>cluster.threads_as_cores</name>
</parameter>
<parameter type="xs:boolean" required="false">
<name>cluster.tunnel_migration</name>
</parameter>
</parameters_set>
</body>
</request>
<response>
<type>Cluster</type>
</response>
</link>
Создать ресурс
[ редактировать ] <link rel="add" href="/api/clusters">
<request>
<http_method>POST</http_method>
<headers>
<header required="true">
<name>Content-Type</name>
<value>application/xml|json</value>
</header>
<header required="false">
<name>Expect</name>
<value>201-created</value>
</header>
<header required="false">
<name>Correlation-Id</name>
<value>any string</value>
</header>
</headers>
<body>
<type>Cluster</type>
<parameters_set>
<parameter type="xs:string" required="true">
<name>cluster.data_center.id|name</name>
</parameter>
<parameter type="xs:string" required="true">
<name>cluster.name</name>
</parameter>
<parameter type="xs:int" required="true">
<name>cluster.version.major</name>
</parameter>
<parameter type="xs:int" required="true">
<name>cluster.version.minor</name>
</parameter>
<parameter type="xs:string" required="true">
<name>cluster.cpu.id</name>
</parameter>
<parameter type="xs:string" required="false">
<name>cluster.description</name>
</parameter>
<parameter type="xs:double" required="false">
<name>cluster.memory_policy.overcommit.percent</name>
</parameter>
<parameter type="xs:boolean" required="false">
<name>cluster.memory_policy.transparent_hugepages.enabled</name>
</parameter>
<parameter type="xs:string" required="false">
<name>cluster.scheduling_policy.policy</name>
</parameter>
<parameter type="xs:int" required="false">
<name>cluster.scheduling_policy.thresholds.low</name>
</parameter>
<parameter type="xs:int" required="false">
<name>cluster.scheduling_policy.thresholds.high</name>
</parameter>
<parameter type="xs:int" required="false">
<name>cluster.scheduling_policy.thresholds.duration</name>
</parameter>
<parameter type="xs:string" required="false">
<name>cluster.error_handling.on_error</name>
</parameter>
<parameter type="xs:boolean" required="false">
<name>cluster.virt_service</name>
</parameter>
<parameter type="xs:boolean" required="false">
<name>cluster.gluster_service</name>
</parameter>
<parameter type="xs:boolean" required="false">
<name>cluster.threads_as_cores</name>
</parameter>
<parameter type="xs:boolean" required="false">
<name>cluster.tunnel_migration</name>
</parameter>
</parameters_set>
</body>
</request>
<response>
<type>Cluster</type>
</response>
</link>
Удалить ресурс
[ редактировать ] <link rel="delete" href="/api/clusters/{cluster:id}">
<request>
<http_method>DELETE</http_method>
<headers>
<header required="false">
<name>Correlation-Id</name>
<value>any string</value>
</header>
</headers>
<url>
<parameters_set>
<parameter context="matrix" type="xs:boolean" required="false">
<name>async</name>
<value>true|false</value>
</parameter>
</parameters_set>
</url>
<body/>
</request>
</link>
Генерация кода
[ редактировать ]Дескриптор URI RSDL
[ редактировать ] <link rel="add" href="/api/clusters">
<request>
<http_method>POST</http_method>
<headers>
<header required="true">
<name>Content-Type</name>
<value>application/xml|json</value>
</header>
<header required="false">
<name>Expect</name>
<value>201-created</value>
</header>
<header required="false">
<name>Correlation-Id</name>
<value>any string</value>
</header>
</headers>
<body>
<type>Cluster</type>
<parameters_set>
<parameter type="xs:string" required="true">
<name>cluster.data_center.id|name</name>
</parameter>
<parameter type="xs:string" required="true">
<name>cluster.name</name>
</parameter>
<parameter type="xs:int" required="true">
<name>cluster.version.major</name>
</parameter>
<parameter type="xs:int" required="true">
<name>cluster.version.minor</name>
</parameter>
<parameter type="xs:string" required="true">
<name>cluster.cpu.id</name>
</parameter>
<parameter type="xs:string" required="false">
<name>cluster.description</name>
</parameter>
<parameter type="xs:double" required="false">
<name>cluster.memory_policy.overcommit.percent</name>
</parameter>
<parameter type="xs:boolean" required="false">
<name>cluster.memory_policy.transparent_hugepages.enabled</name>
</parameter>
<parameter type="xs:string" required="false">
<name>cluster.scheduling_policy.policy</name>
</parameter>
<parameter type="xs:int" required="false">
<name>cluster.scheduling_policy.thresholds.low</name>
</parameter>
<parameter type="xs:int" required="false">
<name>cluster.scheduling_policy.thresholds.high</name>
</parameter>
<parameter type="xs:int" required="false">
<name>cluster.scheduling_policy.thresholds.duration</name>
</parameter>
<parameter type="xs:string" required="false">
<name>cluster.error_handling.on_error</name>
</parameter>
<parameter type="xs:boolean" required="false">
<name>cluster.virt_service</name>
</parameter>
<parameter type="xs:boolean" required="false">
<name>cluster.gluster_service</name>
</parameter>
<parameter type="xs:boolean" required="false">
<name>cluster.threads_as_cores</name>
</parameter>
<parameter type="xs:boolean" required="false">
<name>cluster.tunnel_migration</name>
</parameter>
</parameters_set>
</body>
</request>
<response>
<type>Cluster</type>
</response>
</link>
Сгенерированные подписи кода
[ редактировать ] /**
* Adds Cluster object.
* @param cluster {@link org.ovirt.engine.sdk.entities.Cluster}
* cluster.data_center.id|name
* cluster.name
* cluster.version.major
* cluster.version.minor
* cluster.cpu.id
* [cluster.description]
* [cluster.memory_policy.overcommit.percent]
* [cluster.memory_policy.transparent_hugepages.enabled]
* [cluster.scheduling_policy.policy]
* [cluster.scheduling_policy.thresholds.low]
* [cluster.scheduling_policy.thresholds.high]
* [cluster.scheduling_policy.thresholds.duration]
* [cluster.error_handling.on_error]
* [cluster.virt_service]
* [cluster.gluster_service]
* [cluster.threads_as_cores]
* [cluster.tunnel_migration]
* @return
* {@link Cluster }
* @throws ClientProtocolException
* Signals that HTTP/S protocol error has occurred.
* @throws ServerException
* Signals that an oVirt api error has occurred.
* @throws IOException
* Signals that an I/O exception of some sort has occurred.
*/
public Cluster add(org.ovirt.engine.sdk.entities.Cluster cluster) throws
ClientProtocolException, ServerException, IOException {
....
}
/**
* Adds Cluster object.
* @param cluster {@link org.ovirt.engine.sdk.entities.Cluster}
* cluster.data_center.id|name
* cluster.name
* cluster.version.major
* cluster.version.minor
* cluster.cpu.id
* [cluster.description]
* [cluster.memory_policy.overcommit.percent]
* [cluster.memory_policy.transparent_hugepages.enabled]
* [cluster.scheduling_policy.policy]
* [cluster.scheduling_policy.thresholds.low]
* [cluster.scheduling_policy.thresholds.high]
* [cluster.scheduling_policy.thresholds.duration]
* [cluster.error_handling.on_error]
* [cluster.virt_service]
* [cluster.gluster_service]
* [cluster.threads_as_cores]
* [cluster.tunnel_migration]
* @param expect
* [201-created]
* @param correlationId
* [any string]
* @return
* {@link Cluster }
* @throws ClientProtocolException
* Signals that HTTP/S protocol error has occurred.
* @throws ServerException
* Signals that an oVirt api error has occurred.
* @throws IOException
* Signals that an I/O exception of some sort has occurred.
*/
public Cluster add(org.ovirt.engine.sdk.entities.Cluster cluster, String expect, String correlationId) throws
ClientProtocolException, ServerException, IOException {
....
}
Ссылки
[ редактировать ]- ^ «Язык описания служб RESTful (RSDL)» . Balisage.net .