Feature pages are design documents that developers have created while collaborating on oVirt.

Most of them areoutdated, but provide historical design context.

They arenotuser documentation and should not be treated as such.

Documentation is available here.

RSDL

TOC

Description

RSDL (RESTful Service Description Language) is a machine and human readable XML description of HTTP-based web applications (typically REST web services), it models the resource/s provided by a service, the relationships between them, parameters that has to be supplied for the certain operation, specifies if parameter/s has to be 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’s concentrates in describing URIs as stand along entry points in to the application which can be invoked in a different way, what is makes it human-readable and easily consumed by both humans and machines, (for more details see RSDL wiki).

Concept

self descriptive

RSDL represents different URIs as stand along entry points in to the application, following resource URIs, one can figure out what methods available for the given resources and how the can be consumed.

machine-readable

each URI in RSDL contains all necessary info to generate HTTP request from it, that can be consumed easy accessing this URI internals.

human-readable

each URI in RSDL contains “rel” and “description” describing the meaning of the given operation on the certain URI, humans can easily fetch all available operations for the given collection/resource simply by locating different descriptors with same URI.

Format

    `       ` `       ` `       ` `           ``api.xsd` `           ` `       ` `       ` `           ` `               `                    

                                                                                           

                    ... `               `</headers> `               `<url> `                   `<parameters_set> `                       `<parameter context="query|matrix" type="xs:string" required="true|false"> `                           `<name></name> `                           `<value></value> `                       `</parameter>
                     ... `                   `</parameters_set>
                     ... `           `</request> `           `<name></name> `           `<description></description> `       `</general> `       `<links> `           `<link rel="get|..." href="/api/xxx"> `               `<request> `                   `<http_method>`GET|POST|PUT|DELETE|...`</http_method> `                   `<headers>
                         

                                                                               

                         ... `                   `</headers> `                   `<url> `                       `<parameters_set> `                           `<parameter context="query|matrix" type="" required="true|false"> `                               `<name></name> `                               `<value></value> `                           `</parameter>
                             ... `                       `</parameters_set>
                         ... `                   `</url>
                     

                       `...`                         `                           ` `                               ``FQ-name-to-parameter` `                           `                            ... `                       `                        …                    

               </request>                 `                   `                    ... `               `            </link>            …        </links>    </rsdl>

Components

uri

    `       `

request

    `       ``GET|POST|PUT|DELETE|...` `       `            

                                           

             ... `       `</headers> `       `<url> `           `<parameters_set> `               `<parameter context="query|matrix" type="" required="true|false"> `                   `<name></name> `                   `<value></value> `               `</parameter>
                 ... `           `</parameters_set>
             ... `       `</url>
         

           `...`             `               ` `                   ``FQ-name-to-parameter` `               `                ... `           `            …        

   </request>

response

    `       `        ... `   `

XML schema

  `   ` `     ` `       ` `         ` `       ` `     ` `     ` `   ` ` `

 

  `   ` `   ` ` `

 

  `   ` `     ` `       ` `         ` `           ` `         ` `       ` `     ` `   ` ` `

 

  `   ` `     ` `     ` `       ` `         ` `           ` `         ` `       ` `     ` `   ` `   ` `               ` `         ` `           ` `         ` `       ` `   ` ` `

 

  `   ` `     ` `     ` `     ` `     ` `   ` ` `

  `   ` `     ` `     ` `     ` `     ` `     ` `   ` ` `

 

  `   ` `     ` `   ` ` `

 

  `   ` `     ` `       ` `             ` `             ` `       ` `       ` `         ` `           ` `             ` `           ` `         ` `       ` `       ` `       ` `     ` `   ` ` `

 

  `   ` `     ` `       ` `         ` `       ` `      ` `       ` `         ` `           ` `         ` `       ` `      ` `     ` `   ` ` `

 

  `   ` `     ` `       ` `         ` `           ` `         ` `       ` `     ` `   ` ` `

 

  `   ` `     ` `       ` `         ` `           ` `         ` `       ` `     ` `   ` ` `

 

  `   ` `     ` `       ` `         ` `         ` `       ` `     ` `   ` ` `

 

  `   ` `     ` `       ` `         ` `         ` `       ` `     ` `   ` ` `

 

  `    ` `      ` `      ` `      ` `      ` `      ` `    ` `    ` `    ` ` `

RSDL schema

Usage

examples

list resources

                    `               ``GET` `               `                    

                       `Filter`                        `true|false`                    

               </headers>                 `                   ` `                       ` `                           ``search` `                           ``search query` `                       ` `                       ` `                           ``case_sensitive` `                           ``true|false` `                       ` `                       ` `                           ``max` `                           ``max results` `                       ` `                   ` `               `                

           </request>             `               ``Clusters` `           `        </link>

get resource

                    `               ``GET` `               `                    

                       `Filter`                        `true|false`                    

               </headers>                

           </request>             `               ``Cluster` `           `        </link>

update resource

                    `               ``PUT` `               `                    

                       `Content-Type`                        `application/xml|json`                    

                       `Correlation-Id`                        `any string`                    

               </headers>                

                   `Cluster`                     `                       ` `                           ``cluster.name` `                       ` `                       ` `                           ``cluster.description` `                       ` `                       ` `                           ``cluster.cpu.id` `                       ` `                       ` `                           ``cluster.version.major` `                       ` `                       ` `                           ``cluster.version.minor` `                       ` `                       ` `                           ``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` `                       ` `                   `                

           </request>             `               ``Cluster` `           `        </link>

create resource

                    `               ``POST` `               `                    

                       `Content-Type`                        `application/xml|json`                    

                       `Expect`                        `201-created`                    

                       `Correlation-Id`                        `any string`                    

               </headers>                

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

           </request>             `               ``Cluster` `           `        </link>

delete resource

                    `               ``DELETE` `               `                    

                       `Correlation-Id`                        `any string`                    

               </headers>                 `                   ` `                       ` `                           ``async` `                           ``true|false` `                       ` `                   ` `               `                

           </request>        </link>

code generation

RSDL URI descriptor

                    `               ``POST` `               `                    

                       `Content-Type`                        `application/xml|json`                    

                       `Expect`                        `201-created`                    

                       `Correlation-Id`                        `any string`                    

               </headers>                

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

           </request>             `               ``Cluster` `           `        </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
      *    [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 {
             ....
     }

Repository

  • <git://gerrit.ovirt.org/ovirt-engine>

Maintainer

Michael Pasternak: mpastern@redhat.com