RESTful Service Description Language

Last updated

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

Contents

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

Format

<rsdlrel="rsdl"href="/api?rsdl"><description/><versionrevision="0"build="0"minor="0"major="0"/><schemarel="schema"href="/api?schema"><name>api.xsd</name><description/></schema><generalrel="*"href="/*"><request><headers><headerrequired="true|false"><name/><description/><value/></header></headers><url><parameters_set><parametercontext="query|matrix"type="xs:string"required="true|false"><name/><value/></parameter></parameters_set></url></request><name/><description/></general><links><linkrel="get|..."href="/api/xxx"><request><http_method>GET|POST|PUT|DELETE|...</http_method><headers><headerrequired="true|false"><name/><value/></header></headers><url><parameters_set><parametercontext="query|matrix"type=""required="true|false"><name/><value/></parameter></parameters_set></url><body><type>...</type><parameters_set><parametertype=""required="true|false"><name>FQ-name-to-parameter</name></parameter></parameters_set></body></request><response><type/></response></link></links></rsdl>

Components

URI

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

Request

<request><http_method>GET|POST|PUT|DELETE|...</http_method><headers><headerrequired="true|false"><name></name><value></value></header>       ...     </headers><url><parameters_set><parametercontext="query|matrix"type=""required="true|false"><name></name><value></value></parameter>         ...       </parameters_set>       ...     </url><body><type>...</type><parameters_set><parametertype=""required="true|false"><name>FQ-name-to-parameter</name></parameter>         ...       </parameters_set>       ...     </body></request>

Response

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

XML schema

<xs:elementname="detailedLinks"type="DetailedLinks"/><xs:complexTypename="DetailedLinks"><xs:sequence><xs:annotation><xs:appinfo><jaxb:propertyname="links"/></xs:appinfo></xs:annotation><xs:elementtype="DetailedLink"name="link"maxOccurs="unbounded"/></xs:sequence></xs:complexType><xs:elementname="link"type="Link"/><xs:complexTypename="Link"><xs:attributename="href"type="xs:string"/><xs:attributename="rel"type="xs:string"/></xs:complexType><xs:elementname="url"type="Url"/><xs:complexTypename="Url"><xs:sequence><xs:elementref="parameters_set"maxOccurs="unbounded"minOccurs="0"><xs:annotation><xs:appinfo><jaxb:propertyname="ParametersSets"/></xs:appinfo></xs:annotation></xs:element></xs:sequence></xs:complexType><xs:elementname="body"type="Body"/><xs:complexTypename="Body"><xs:sequence><xs:elementname="type"type="xs:string"minOccurs="1"maxOccurs="1"/><xs:elementref="parameters_set"maxOccurs="unbounded"minOccurs="0"><xs:annotation><xs:appinfo><jaxb:propertyname="ParametersSets"/></xs:appinfo></xs:annotation></xs:element></xs:sequence><xs:attributename="required"type="xs:boolean"><xs:annotation><xs:appinfo><jaxb:propertygenerateIsSetMethod="false"/></xs:appinfo></xs:annotation></xs:attribute></xs:complexType><xs:elementname="request"type="Request"/><xs:complexTypename="Request"><xs:sequence><xs:elementname="http_method"type="HttpMethod"minOccurs="1"maxOccurs="1"/><xs:elementref="headers"minOccurs="0"maxOccurs="1"/><xs:elementref="url"minOccurs="0"maxOccurs="1"/><xs:elementref="body"minOccurs="0"maxOccurs="1"/></xs:sequence></xs:complexType><xs:simpleTypename="HttpMethod"><xs:restrictionbase="xs:string"><xs:enumerationvalue="GET"/><xs:enumerationvalue="POST"/><xs:enumerationvalue="PUT"/><xs:enumerationvalue="DELETE"/><xs:enumerationvalue="OPTIONS"/></xs:restriction></xs:simpleType><xs:elementname="response"type="Response"/><xs:complexTypename="Response"><xs:sequence><xs:elementname="type"type="xs:string"minOccurs="1"maxOccurs="1"/></xs:sequence></xs:complexType><xs:elementname="parameter"type="Parameter"/><xs:complexTypename="Parameter"><xs:complexContent><xs:extensionbase="BaseResource"><xs:sequence><xs:elementname="value"type="xs:string"minOccurs="1"maxOccurs="1"/><xs:elementref="parameters_set"minOccurs="0"maxOccurs="1"/></xs:sequence><xs:attributename="required"type="xs:boolean"><xs:annotation><xs:appinfo><jaxb:propertygenerateIsSetMethod="false"/></xs:appinfo></xs:annotation></xs:attribute><xs:attributename="type"type="xs:string"/><xs:attributename="context"type="xs:string"/></xs:extension></xs:complexContent></xs:complexType><xs:elementname="header"type="Header"/><xs:complexTypename="Header"><xs:complexContent><xs:extensionbase="BaseResource"><xs:sequence><xs:elementname="value"type="xs:string"minOccurs="1"maxOccurs="1"/></xs:sequence><xs:attributename="required"type="xs:boolean"><xs:annotation><xs:appinfo><jaxb:propertygenerateIsSetMethod="false"/></xs:appinfo></xs:annotation></xs:attribute></xs:extension></xs:complexContent></xs:complexType><xs:elementname="headers"type="Headers"/><xs:complexTypename="Headers"><xs:sequence><xs:elementref="header"maxOccurs="unbounded"><xs:annotation><xs:appinfo><jaxb:propertyname="Headers"/></xs:appinfo></xs:annotation></xs:element></xs:sequence></xs:complexType><xs:elementname="parameters_set"type="ParametersSet"/><xs:complexTypename="ParametersSet"><xs:sequence><xs:elementref="parameter"maxOccurs="unbounded"minOccurs="0"><xs:annotation><xs:appinfo><jaxb:propertyname="Parameters"/></xs:appinfo></xs:annotation></xs:element></xs:sequence></xs:complexType><xs:elementname="schema"type="Schema"/><xs:complexTypename="Schema"><xs:complexContent><xs:extensionbase="Link"><xs:sequence><xs:elementname="name"type="xs:string"minOccurs="0"maxOccurs="1"/><xs:elementname="description"type="xs:string"minOccurs="0"maxOccurs="1"/></xs:sequence></xs:extension></xs:complexContent></xs:complexType><xs:elementname="general_metadata"type="GeneralMetadata"/><xs:complexTypename="GeneralMetadata"><xs:complexContent><xs:extensionbase="DetailedLink"><xs:sequence><xs:elementname="name"type="xs:string"minOccurs="0"maxOccurs="1"/><xs:elementname="description"type="xs:string"minOccurs="0"maxOccurs="1"/></xs:sequence></xs:extension></xs:complexContent></xs:complexType><xs:elementname="rsdl"type="RSDL"/><xs:complexTypename="RSDL"><xs:sequence><xs:elementname="description"type="xs:string"minOccurs="0"/><xs:elementtype="Version"name="version"minOccurs="0"maxOccurs="1"/><xs:elementref="schema"minOccurs="0"maxOccurs="1"/><xs:elementtype="GeneralMetadata"name="general"minOccurs="0"maxOccurs="1"/><xs:elementtype="DetailedLinks"name="links"minOccurs="0"/></xs:sequence><xs:attributename="href"type="xs:string"/><xs:attributename="rel"type="xs:string"/></xs:complexType>

Examples

List resources

<linkrel="get"href="/api/clusters"><request><http_method>GET</http_method><headers><headerrequired="false"><name>Filter</name><value>true|false</value></header></headers><url><parameters_set><parametercontext="query"type="xs:string"required="false"><name>search</name><value>search query</value></parameter><parametercontext="matrix"type="xs:boolean"required="false"><name>case_sensitive</name><value>true|false</value></parameter><parametercontext="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

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

Update resource

<linkrel="update"href="/api/clusters/{cluster:id}"><request><http_method>PUT</http_method><headers><headerrequired="true"><name>Content-Type</name><value>application/xml|json</value></header><headerrequired="false"><name>Correlation-Id</name><value>any string</value></header></headers><body><type>Cluster</type><parameters_set><parametertype="xs:string"required="false"><name>cluster.name</name></parameter><parametertype="xs:string"required="false"><name>cluster.description</name></parameter><parametertype="xs:string"required="false"><name>cluster.cpu.id</name></parameter><parametertype="xs:int"required="false"><name>cluster.version.major</name></parameter><parametertype="xs:int"required="false"><name>cluster.version.minor</name></parameter><parametertype="xs:double"required="false"><name>cluster.memory_policy.overcommit.percent</name></parameter><parametertype="xs:boolean"required="false"><name>cluster.memory_policy.transparent_hugepages.enabled           </name></parameter><parametertype="xs:string"required="false"><name>cluster.scheduling_policy.policy</name></parameter><parametertype="xs:int"required="false"><name>cluster.scheduling_policy.thresholds.low</name></parameter><parametertype="xs:int"required="false"><name>cluster.scheduling_policy.thresholds.high</name></parameter><parametertype="xs:int"required="false"><name>cluster.scheduling_policy.thresholds.duration</name></parameter><parametertype="xs:string"required="false"><name>cluster.error_handling.on_error</name></parameter><parametertype="xs:boolean"required="false"><name>cluster.virt_service</name></parameter><parametertype="xs:boolean"required="false"><name>cluster.gluster_service</name></parameter><parametertype="xs:boolean"required="false"><name>cluster.threads_as_cores</name></parameter><parametertype="xs:boolean"required="false"><name>cluster.tunnel_migration</name></parameter></parameters_set></body></request><response><type>Cluster</type></response></link>

Create resource

<linkrel="add"href="/api/clusters"><request><http_method>POST</http_method><headers><headerrequired="true"><name>Content-Type</name><value>application/xml|json</value></header><headerrequired="false"><name>Expect</name><value>201-created</value></header><headerrequired="false"><name>Correlation-Id</name><value>any string</value></header></headers><body><type>Cluster</type><parameters_set><parametertype="xs:string"required="true"><name>cluster.data_center.id|name</name></parameter><parametertype="xs:string"required="true"><name>cluster.name</name></parameter><parametertype="xs:int"required="true"><name>cluster.version.major</name></parameter><parametertype="xs:int"required="true"><name>cluster.version.minor</name></parameter><parametertype="xs:string"required="true"><name>cluster.cpu.id</name></parameter><parametertype="xs:string"required="false"><name>cluster.description</name></parameter><parametertype="xs:double"required="false"><name>cluster.memory_policy.overcommit.percent</name></parameter><parametertype="xs:boolean"required="false"><name>cluster.memory_policy.transparent_hugepages.enabled</name></parameter><parametertype="xs:string"required="false"><name>cluster.scheduling_policy.policy</name></parameter><parametertype="xs:int"required="false"><name>cluster.scheduling_policy.thresholds.low</name></parameter><parametertype="xs:int"required="false"><name>cluster.scheduling_policy.thresholds.high</name></parameter><parametertype="xs:int"required="false"><name>cluster.scheduling_policy.thresholds.duration</name></parameter><parametertype="xs:string"required="false"><name>cluster.error_handling.on_error</name></parameter><parametertype="xs:boolean"required="false"><name>cluster.virt_service</name></parameter><parametertype="xs:boolean"required="false"><name>cluster.gluster_service</name></parameter><parametertype="xs:boolean"required="false"><name>cluster.threads_as_cores</name></parameter><parametertype="xs:boolean"required="false"><name>cluster.tunnel_migration</name></parameter></parameters_set></body></request><response><type>Cluster</type></response></link>

Delete resource

<linkrel="delete"href="/api/clusters/{cluster:id}"><request><http_method>DELETE</http_method><headers><headerrequired="false"><name>Correlation-Id</name><value>any string</value></header></headers><url><parameters_set><parametercontext="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

<linkrel="add"href="/api/clusters"><request><http_method>POST</http_method><headers><headerrequired="true"><name>Content-Type</name><value>application/xml|json</value></header><headerrequired="false"><name>Expect</name><value>201-created</value></header><headerrequired="false"><name>Correlation-Id</name><value>any string</value></header></headers><body><type>Cluster</type><parameters_set><parametertype="xs:string"required="true"><name>cluster.data_center.id|name</name></parameter><parametertype="xs:string"required="true"><name>cluster.name</name></parameter><parametertype="xs:int"required="true"><name>cluster.version.major</name></parameter><parametertype="xs:int"required="true"><name>cluster.version.minor</name></parameter><parametertype="xs:string"required="true"><name>cluster.cpu.id</name></parameter><parametertype="xs:string"required="false"><name>cluster.description</name></parameter><parametertype="xs:double"required="false"><name>cluster.memory_policy.overcommit.percent</name></parameter><parametertype="xs:boolean"required="false"><name>cluster.memory_policy.transparent_hugepages.enabled</name></parameter><parametertype="xs:string"required="false"><name>cluster.scheduling_policy.policy</name></parameter><parametertype="xs:int"required="false"><name>cluster.scheduling_policy.thresholds.low</name></parameter><parametertype="xs:int"required="false"><name>cluster.scheduling_policy.thresholds.high</name></parameter><parametertype="xs:int"required="false"><name>cluster.scheduling_policy.thresholds.duration</name></parameter><parametertype="xs:string"required="false"><name>cluster.error_handling.on_error</name></parameter><parametertype="xs:boolean"required="false"><name>cluster.virt_service</name></parameter><parametertype="xs:boolean"required="false"><name>cluster.gluster_service</name></parameter><parametertype="xs:boolean"required="false"><name>cluster.threads_as_cores</name></parameter><parametertype="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     *    [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.     */publicClusteradd(org.ovirt.engine.sdk.entities.Clustercluster)throwsClientProtocolException,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.     */publicClusteradd(org.ovirt.engine.sdk.entities.Clustercluster,Stringexpect,StringcorrelationId)throwsClientProtocolException,ServerException,IOException{....}

Related Research Articles

In computer science, test coverage is a percentage measure of the degree to which the source code of a program is executed when a particular test suite is run. A program with high test coverage has more of its source code executed during testing, which suggests it has a lower chance of containing undetected software bugs compared to a program with low test coverage. Many different metrics can be used to calculate test coverage. Some of the most basic are the percentage of program subroutines and the percentage of program statements called during execution of the test suite.

A query string is a part of a uniform resource locator (URL) that assigns values to specified parameters. A query string commonly includes fields added to a base URL by a Web browser or other client application, for example as part of an HTML, choosing the appearance of a page, or jumping to positions in multimedia content.

An XML schema is a description of a type of XML document, typically expressed in terms of constraints on the structure and content of documents of that type, above and beyond the basic syntactical constraints imposed by XML itself. These constraints are generally expressed using some combination of grammatical rules governing the order of elements, Boolean predicates that the content must satisfy, data types governing the content of elements and attributes, and more specialized rules such as uniqueness and referential integrity constraints.

<span class="mw-page-title-main">Java syntax</span> Set of rules defining correctly structured programs

The syntax of Java refers to the set of rules defining how a Java program is written and interpreted.

In computer science, the Boolean is a data type that has one of two possible values which is intended to represent the two truth values of logic and Boolean algebra. It is named after George Boole, who first defined an algebraic system of logic in the mid 19th century. The Boolean data type is primarily associated with conditional statements, which allow different actions by changing control flow depending on whether a programmer-specified Boolean condition evaluates to true or false. It is a special case of a more general logical data type—logic does not always need to be Boolean.

The computer programming languages C and Pascal have similar times of origin, influences, and purposes. Both were used to design their own compilers early in their lifetimes. The original Pascal definition appeared in 1969 and a first compiler in 1970. The first version of C appeared in 1972.

<span class="mw-page-title-main">C data types</span> Data types supported by the C programming language

In the C programming language, data types constitute the semantics and characteristics of storage of data elements. They are expressed in the language syntax in form of declarations for memory locations or variables. Data types also determine the types of operations or methods of processing of data elements.

XMLBeans is a Java-to-XML binding framework which is part of the Apache Software Foundation XML project.

The syntax of JavaScript is the set of rules that define a correctly structured JavaScript program.

In the Java computer programming language, an annotation is a form of syntactic metadata that can be added to Java source code. Classes, methods, variables, parameters and Java packages may be annotated. Like Javadoc tags, Java annotations can be read from source files. Unlike Javadoc tags, Java annotations can also be embedded in and read from Java class files generated by the Java compiler. This allows annotations to be retained by the Java virtual machine at run-time and read via reflection. It is possible to create meta-annotations out of the existing ones in Java.

In computer programming, an enumerated type is a data type consisting of a set of named values called elements, members, enumeral, or enumerators of the type. The enumerator names are usually identifiers that behave as constants in the language. An enumerated type can be seen as a degenerate tagged union of unit type. A variable that has been declared as having an enumerated type can be assigned any of the enumerators as a value. In other words, an enumerated type has values that are different from each other, and that can be compared and assigned, but are not specified by the programmer as having any particular concrete representation in the computer's memory; compilers and interpreters can represent them arbitrarily.

In computing, an attribute is a specification that defines a property of an object, element, or file. It may also refer to or set the specific value for a given instance of such. For clarity, attributes should more correctly be considered metadata. An attribute is frequently and generally a property of a property. However, in actual usage, the term attribute can and is often treated as equivalent to a property depending on the technology being discussed. An attribute of an object usually consists of a name and a value; of an element, a type or class name; of a file, a name and extension.

The Web Application Description Language (WADL) is a machine-readable XML description of HTTP-based web services. WADL models the resources provided by a service and the relationships between them. WADL is intended to simplify the reuse of web services that are based on the existing 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. WADL was submitted to the World Wide Web Consortium by Sun Microsystems on 31 August 2009, but the consortium has no current plans to standardize it. WADL is the REST equivalent of SOAP's Web Services Description Language (WSDL), which can also be used to describe REST web services.

In computer science, marshalling or marshaling is the process of transforming the memory representation of an object into a data format suitable for storage or transmission. It is typically used when data must be moved between different parts of a computer program or from one program to another.

XPath is an expression language designed to support the query or transformation of XML documents. It was defined by the World Wide Web Consortium (W3C) and can be used to compute values from the content of an XML document. Support for XPath exists in applications that support XML, such as web browsers, and many programming languages.

Data Format Description Language, published as an Open Grid Forum Proposed Recommendation in January 2011, is a modeling language for describing general text and binary data in a standard way. A DFDL model or schema allows any text or binary data to be read from its native format and to be presented as an instance of an information set.. The same DFDL schema also allows data to be taken from an instance of an information set and written out to its native format.

Fuzzy Markup Language (FML) is a specific purpose markup language based on XML, used for describing the structure and behavior of a fuzzy system independently of the hardware architecture devoted to host and run it.

gSOAP is a C and C++ software development toolkit for SOAP/XML web services and generic XML data bindings. Given a set of C/C++ type declarations, the compiler-based gSOAP tools generate serialization routines in source code for efficient XML serialization of the specified C and C++ data structures. Serialization takes zero-copy overhead.

Interpolation sort is a kind of bucket sort. It uses an interpolation formula to assign data to the bucket. A general interpolation formula is:

References

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