Langage de description de services RESTful

(Learn how and when to remove this message)

Le langage de description de service RESTful ( RSDL ) est une description XML lisible par machine et par l'homme des applications Web basées sur HTTP (généralement des services Web REST ).

Le langage (défini par Michael Pasternak lors de ses travaux sur l'API RESTful oVirt ) permet de documenter le modèle des ressources fournies par un service, les relations entre elles, ainsi que les opérations et les paramètres qui doivent être fournis pour les opérations. Il précise si des paramètres sont obligatoires et décrit les surcharges possibles sous forme d'ensembles de paramètres.

RSDL a pour objectif de simplifier la réutilisation des services Web basés sur l'architecture HTTP du Web. Il est indépendant de la plate-forme et du langage et vise à promouvoir la réutilisation des applications au-delà de l'utilisation de base dans un navigateur Web, tant par les humains que par les machines.

Contrairement à WADL , il se concentre sur la description des URI en tant que points d'entrée autonomes dans l'application qui peuvent être invoqués de différentes manières, ne nécessite pas de parcourir les composants URI pour comprendre la structure de l'URI et prend en charge les surcharges de paramètres URI/en-têtes/corps. Cela le rend lisible par l'homme et facilement utilisable par les humains et les machines.

Propriétés

Autodescriptif : RSDL représente différents URI en tant que points d'entrée autonomes dans l'application. En suivant les URI des ressources, on peut déterminer quelles méthodes sont disponibles pour les ressources données et comment ces ressources peuvent être consommées.
Lisible par machine : chaque URI dans RSDL contient toutes les informations nécessaires pour générer une requête HTTP à partir de celui-ci, qui peut être facilement consommée en accédant aux éléments internes de l'URI.
Lisible par l'homme : chaque URI dans RSDL contient les attributs « rel » et « description » décrivant la signification de l'opération donnée sur cet URI. Les humains peuvent facilement récupérer toutes les opérations disponibles pour une collection/ressource donnée simplement en localisant différents descripteurs dans le même 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-nom-à-paramètre </name> </parameter> </parameters_set> </body> </request> <response> <type /> </response> </link> </links> </rsdl>

Composants

URI

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

Demande

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

Réponse

<réponse> 
<type></type> ... </réponse>

Schéma XML

<xs:element name= "liens détaillés" type= "liens détaillés" />
<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= "lien" type= "Lien" />
<xs:complexType name= "Lien" > <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= "corps" type= "Corps" />
<xs:complexType name= "Corps" > <xs:séquence> <xs:élément name= "type" type= "xs:chaîne" minOccurs= "1" maxOccurs= "1" /> <xs:élément ref= "ensemble_de_paramètres" maxOccurs= "illimité" minOccurs= "0" > <xs:annotation> <xs:appinfo> <jaxb:property name= "Ensembles_de_paramètres" /> </xs:appinfo> </xs:annotation> </xs:élément> </xs:séquence> <xs:attribut name= "requis" type= "xs:booléen" > <xs:annotation> <xs:appinfo> <jaxb:property generateIsSetMethod= "false" /> </xs:appinfo> </xs:annotation> </xs:attribute> </xs:complexType>
<xs:element name= "requête" type= "Requête" />
<xs:complexType name= "Requête" > <xs:sequence> <xs:element name= "http_method" type= "HttpMethod" minOccurs= "1" maxOccurs= "1" /> <xs:element ref= "en-têtes" minOccurs= "0" maxOccurs= "1" /> <xs:element ref= "url" minOccurs= "0" maxOccurs= "1" /> <xs:element ref= "corps" 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= "Réponse" />
<xs:complexType name= "Réponse" > <xs:sequence> <xs:element name= "type" type= "xs:string" minOccurs= "1" maxOccurs= "1" /> </xs:sequence> </xs:complexType>
<xs:element name= "paramètre" type= "Paramètre" />
<xs:complexType name= "Paramètre" > <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= "en-tête" type= "En-tête" />
<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= "en-têtes" type= "En-têtes" />
<xs:complexType name= "En-têtes" > <xs:sequence> <xs:element ref= "en-tête" maxOccurs= "illimité" > <xs:annotation> <xs:appinfo> <jaxb:property name= "En-têtes" /> </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= "schéma" type= "Schéma" />
<xs:complexType name= "Schéma" > <xs:complexContent> <xs:extension base= "Lien" > <xs:séquence> <xs:element name= "nom" 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>

Exemples

Liste des ressources

<link rel= "get" href= "/api/clusters" > <request> <http_method> GET </http_method> <headers> <header required= "false" > <name> Filtre </name> <value> true|false </value> </header> </headers> <url> <parameters_set> <parameter context= "query" type= "xs:string" required= "false" > <name> recherche </name> <value> requête de recherche </value> </parameter> <parameter context= "matrix" type= "xs:boolean" required= "false" > <name> sensible à la casse </name> <value> true|false </value> </parameter> <parameter context= "matrix" type= "xs:int" required = " false" > <name> max </name> <value> nombre maximal de résultats </value> </parameter> </parameters_set> </url> <body/> </request> <response> <type> Clusters </type> </response> </link>

Obtenir des ressources

<link rel= "get" href= "/api/clusters/{cluster:id}" > <request> <http_method> GET </http_method> <headers> <header required= "false" > <name> Filtre </name> <value> true|false </value> </header> </headers> <body/> </request> <response> <type> Cluster </type> </response> </link>

Mettre à jour la ressource

<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.politique </name> </parameter> <parameter type= "xs:int" required= "false" > <name> cluster.scheduling_policy.thresholds.low </name> </parameter> <parameter type= "xs:int" required= "false" >
<nom> cluster.scheduling_policy.thresholds.high </nom> 
</parameter> < parameter type= " xs:int" required = "false" > <nom> cluster.scheduling_policy.thresholds.duration </nom> </parameter> < parameter type= "xs:string " required= "false" > <nom> cluster.error_handling.on_error </nom> </parameter> < parameter type= "xs:boolean" required= "false" > <nom> cluster.virt_service </nom> </parameter> < parameter type= "xs:boolean" required = " false " > <nom> cluster.gluster_service </nom> </parameter> < parameter type = " xs :boolean " required= "false" > <nom> cluster.threads_as_cores </nom> </parameter> <parameter type= "xs:boolean" required= "false" > <name> cluster.tunnel_migration </name> </parameter> </parameters_set> </body> </request> <response> <type> Cluster </type> </response> </link>

Créer une ressource

<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.pourcentage </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>

Supprimer la ressource

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

Génération de code

Descripteur d'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.pourcentage </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>

Signature(s) de code générée(s)

/** 
 * Ajoute un objet Cluster. 
 * @param cluster {@link org.ovirt.engine.sdk.entities.Cluster} 
 * cluster.data_center.id|nom 
 * 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 
 * Signale qu'une erreur de protocole HTTP/S s'est produite. 
 * @throws ServerException 
 * Signale qu'une erreur d'API oVirt s'est produite. 
 * @throws IOException 
 * Signale qu'une exception d'E/S d'une certaine sorte s'est produite. 
 */ 
public Cluster add ( org . ovirt . engine . sdk . entity . Cluster cluster ) throws ClientProtocolException , ServerException , IOException {
.... 
}
/** 
 * Ajoute un objet Cluster. 
 * @param cluster {@link org.ovirt.engine.sdk.entities.Cluster} 
 * cluster.data_center.id|nom 
 * 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 
 * Signale qu'une erreur de protocole HTTP/S s'est produite. 
 * @throws ServerException 
 * Signale qu'une erreur d'API oVirt s'est produite. 
 * @throws IOException 
 * Signale qu'une exception d'E/S d'une certaine sorte s'est produite. 
 */ 
public Cluster add ( org . ovirt . engine . sdk . entity . Cluster cluster , String expect , String correlationId ) throws ClientProtocolException , ServerException , IOException { .... }