French
DeutschRESTful Service Description Language
 | This article has multiple issues. Please help improve it or discuss these issues on the talk page. (Learn how and when to remove these template messages)
|
The RESTful Service Description Language (RSDL) is a machine- and human-readable XML description of HTTP-based web applications (typically REST web services).[1]
The language (defined by Michael Pasternak during his work on oVirt RESTful API) allows documenting the model of the resource(s) provided by a service, the relationships between them, and operations and the parameters that must be supplied for the operations. It specifies if parameters are mandated; and describes possible overloads as parameters sets.
RSDL is intended to simplify the reuse of web services that are based on the HTTP architecture of the web. It is platform- and language-independent and aims to promote reuse of applications beyond the basic use in a web browser by both humans and machines.
Unlike WADL, it concentrates on describing URIs as stand-alone entry points in to the application which can be invoked in different ways, does not require traversing over URI components to figure out URI structure, and supports URI/Headers/body parameters overloads. This makes it human-readable and easily consumed by both humans and machines.
Properties
[edit]- Self descriptive: RSDL represents different URIs as stand-alone entry points into the application. Following resource URIs, one can figure out which methods are available for the given resources and how those resources can be consumed.
- Machine-readable: Each URI in RSDL contains all the necessary information to generate an HTTP request from it, which can be easily consumed by accessing the URI internals.
- Human-readable: Each URI in RSDL contains "rel" and "description" attributes describing the meaning of the given operation on that URI. Humans can easily fetch all available operations for a given collection/resource simply by locating different descriptors within the same URI.
Format
[edit]<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> Components
[edit]URI
[edit] <links> <link rel="get|..." href="/api/xxx"> Request
[edit] <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
[edit] <response> <type></type> ... </response> XML schema
[edit] <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> Examples
[edit]List resources
[edit] <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> Get resource
[edit] <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> Update resource
[edit] <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> Create resource
[edit] <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> Delete resource
[edit] <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> Code generation
[edit]RSDL URI descriptor
[edit] <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> Generated code signature(s)
[edit] /** * 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 { .... } References
[edit]- ^ "RESTful Service Description Language (RSDL)". balisage.net.