Product SiteDocumentation Site

1.4. Representations

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.