RESTful Service Description Language
The RESTful Service Description Language is a machine- and human-readable XML description of HTTP-based web applications.
The language allows documenting the model of the resource provided by a service, the relationships between them, and operations and the parameters that must be supplied for the operations. It specifies whether 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
Components
URI
Request
...
...
...
...
...
Response
...
XML schema
Examples
List resources
Get resource
Update resource
Create resource
Delete resource
Code generation
RSDL URI descriptor
Generated code signature(s)
/**
* Adds Cluster object.
* @param cluster
* cluster.data_center.id|name
* cluster.name
* cluster.version.major
* cluster.version.minor
* cluster.cpu.id
*
*
*
*
*
*
*
*
*
*
*
*
* @return
*
* @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 throws
ClientProtocolException, ServerException, IOException
/**
* Adds Cluster object.
* @param cluster
* cluster.data_center.id|name
* cluster.name
* cluster.version.major
* cluster.version.minor
* cluster.cpu.id
*
*
*
*
*
*
*
*
*
*
*
*
* @param expect
*
* @param correlationId
*
* @return
*
* @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 throws
ClientProtocolException, ServerException, IOException