Misplaced Pages

RESTful Service Description Language

Article snapshot taken from Wikipedia with creative commons attribution-sharealike license. Give it a read and then ask your questions in the chat. We can research this topic together.
XML description of HTTP-based web APIs
This article has multiple issues. Please help improve it or discuss these issues on the talk page. (Learn how and when to remove these messages)
This article needs additional citations for verification. Please help improve this article by adding citations to reliable sources. Unsourced material may be challenged and removed.
Find sources: "RESTful Service Description Language" – news · newspapers · books · scholar · JSTOR (April 2015) (Learn how and when to remove this message)
The topic of this article may not meet Misplaced Pages's general notability guideline. Please help to demonstrate the notability of the topic by citing reliable secondary sources that are independent of the topic and provide significant coverage of it beyond a mere trivial mention. If notability cannot be shown, the article is likely to be merged, redirected, or deleted.
Find sources: "RESTful Service Description Language" – news · newspapers · books · scholar · JSTOR (April 2015) (Learn how and when to remove this message)
This article focuses too much on specific examples. Please help improve this article by adding sources that evaluate within a broader context. (April 2015)
This article may be too technical for most readers to understand. Please help improve it to make it understandable to non-experts, without removing the technical details. (April 2015) (Learn how and when to remove this message)
(Learn how and when to remove this message)

The RESTful Service Description Language (RSDL) is a machine- and human-readable XML description of HTTP-based web applications (typically REST web services).

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

  • 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

<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

URI

    <links>
        <link rel="get|..." href="/api/xxx">

Request

  <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

    <response>
        <type></type>
        ...
    </response>

XML schema

  <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

List resources

        <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

        <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

  <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

        <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

        <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

RSDL URI descriptor

        <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)

    /**
     * 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
     *    
     *    
     *    
     *    
     *    
     *    
     *    
     *    
     *    
     *    
     *    
     *    
     * @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
     *    
     *    
     *    
     *    
     *    
     *    
     *    
     *    
     *    
     *    
     *    
     *    
     * @param expect
     *    
     * @param correlationId
     *    
     * @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

  1. "RESTful Service Description Language (RSDL)". balisage.net.
Category: