Access to a resource URI in a RESTful web service does not mean direct access to the resource itself but to an abstraction of the resource. This abstraction is called a representation. The API constructs representations using various formats but this documentation focuses primarily on XML representations.
When working with a specific resource, the API constructs a representation using elements. When an API user accesses http://www.example.com/collection/resource
, an XML resource representation structures elements in the following way:
<resource>
<element_one>value one</element_one>
<element_two>value two</element_two>
<element_three>value three</element_three>
...
</resource>
Elements can also contain attributes
, which provide information about the element itself:
<resource>
<element attribute="value"/>
...
</resource>
A virtual machine resource contains elements such as machine type, operational status, memory in bytes, CPUs and creation time. These elements form a basic XML structure for a virtual machine resource representation:
<vm>
<type>server</type>
<status>UP</status>
<memory>536870912</memory>
<cpu>
<topology cores="1" sockets="1"/>
</cpu>
<creation_time>2011-01-25T13:53:15.103+10:00</creation_time>
</vm>
This example shows how the resource representation portrays complex elements, such as cpu
and topology
information. Complex elements contain sub-elements to depict multiple properties of a single element. This demonstrates how REST representations use XML to depict very specific aspects of resources and their elements.