RSDL

RSDL (RESTful Service Description Language, «мова опису RESTful сервісів») — це машино- й людино-читабельний XML опис HTTP вебзастосунків (зазвичай, вебсервісів типу REST).

Ця мова (розроблена Майклом Пастернаком^[1] у процесі його роботи над RESTful API для oVirt) надає можливість описати модель ресурсів, які надає сервіс, взаємозв’язки між ними, та дії й параметри, які мають бути передані до виконуваних методів. Вона визначає чи треба передавати параметри, а також описує можливі варіації множин параметрів.

RSDL покликаний спростити повторне використання вебсервісів, які базуються на HTTP-архітектурі вебу. Він є платформо- та мово-незалежним і має на меті сприяння повторному використанню застосунків, окрім основного використання у веббраузерах, як людьми, так і машинами.

На відміну від WADL, він зосереджується на описі URI як автономних точок входу у застосунок, які можуть бути викликані різними способами, не потребує слідування через компоненти URI, щоб визначити структуру URI, та підтримує перевантаження параметрів URI/заголовків/тіла. Це робить його легкочитабельним для людей та простим для використання і людьми, й машинами.

Самоописуваний

RSDL представляє різні URI як автономні точки входу у застосунок. Слідуючи за URI ресурсів можна дізнатися які методи доступні для заданих ресурсів і як цими ресурси можна користуватися

Зрозумілий машинам

Кожен URI у RSDL містить усю необхідну інформацію для формування з нього HTTP запиту. Цю інформацію можна отримати із внутрішніх частин URI.

Зрозумілий людям

Кожен URI у RSDL містить атрибути "rel" та "description", які описують значення заданої операції над цим URI. Люди можуть дізнатися всі доступні операції для вказаної колекції/ресурсу, просто знайшовши різні дескриптори за тим самим URI.

Формат

<?xml version="1.0" encoding="utf-8"?>
  <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>

Компоненти

URI

    <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

Див. також: RSDL 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>

Приклади

Перелік ресурсів

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

Генерація коду

Дескриптор RSDL URI

        <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 Service Description Language (RSDL) [Архівовано 21 квітня 2014 у Wayback Machine.](англ.)
RSDL. Describing RESTful Services Without Tight Coupling(англ.)
Exporting and Interactively Querying Web Service-Accessed Sources: The CLIDE System [Архівовано 23 вересня 2015 у Wayback Machine.](англ.)

Примітки

↑ Профіль автора RSDL на Linkedin^{[недоступне посилання з серпня 2019]}англ. Michael Pasternak

[linkedin-1] Профіль автора RSDL на Linkedin^{[недоступне посилання з серпня 2019]}англ. Michael Pasternak

[1]