Vangaea
User Guide
- Getting Started
- Object Model
- Database Design
- RESTful Design
- Single Sign-On
Project Documentation
Vangaea is built using a RESTful architecture. When making API calls against Vangaea, a developer is simply acessing a URL. The simplicity in this approach means Vangaea is available to not just heavy-hitting languages such as C# and Java, but also to the languages of the Internet such as Ruby, PHP, Python, etc.
RESTful URIs
There are several important URIs to be aware of when using Vangaea. The tables below list the ones that you will use most often. An important note about the place holders (the text in between curly braces in the URIs). These are known as URI IDs -- a Vangaean concept. For more information about URI IDs, please see the section below discussing them in detail.
Notes
One important note, wherever a URI ID is specified an asterik is an allowed substitute. The use of an asterik informs Vangaea that all elements should be considered.
Root URIs
These are the URIs that are at the root of Vangaea.
| / | The root URI. Unauthenticated requests will be redirected to /r/login. Once authenticated the client will be redirected to the root virtualization URI. |
| /r/login | The login URI. This is the only URI that must be guarded in order to force an authentication. No matter your web server, all you have to do ensure that authentication takes place is to protect this path and a Vangaea login will be forced. |
Administrative URIs
These are the URIs that have to do with Vangaea's own administrative API.
| /r/a | The root administrative URI. |
Virtualization URIs
There are the URIs that have to do with the virtualiation API.
| /r/v | The root virtualization URI. This URI aggregates all of servers available to the authenticated user into a single result. |
Server URIs
These are the URIs that have to do with servers.
| /r/v/servers | This URI enumerates all servers available to the authenticated user. |
| /r/v/servers/{server} | This URI retrieves the server specified by the given URI ID. |
Host URIs
These are the URIs that have to do with hosts.
| /r/v/hosts | This URI enumerates all of hosts available to the authenticated user. |
| /r/v/hosts/{host} | This URI retrieves the host specified by the given URI ID. |
| /r/v/servers/{server}/hosts | This URI enumerates all of the hosts available to given server and the authenticated user. |
| /r/v/servers/{server}/hosts/{host} | This URI retrieves the host specified by the given URI ID. |
Virtual Machine URIs
These are the URIs that have to do with virtual machines.
| /r/v/vms | This URI enumerates all of the VMs available to the authenticated user. |
| /r/v/vms/{vm} | This URI retrieves the VM specified by the given URI ID. |
| /r/v/hosts/{host}/vms | This URI enumerates all of the VMs available to the given host and the authenticated user. |
| /r/v/servers/{server}/vms | This URI enumerates all of the VMs available to the given server and the authenticated user. |
| /r/v/servers/{server}/vms/{vm} | This URI retrieves the VM specified by the given URI ID. |
| /r/v/servers/{server}/hosts/{host}/vms | This URI enumerates all of the VMs available to the given host and the authenticated user. |
| /r/v/servers/{server}/hosts/{host}/vms/{vm} | This URI retrieves the VM specified by the given URI ID. |
Action URIs
These are the URIs used to execute actions with Vangaea. All actions return a task object.
| /r/v/vms/{vm}/{action} | Executes an action on the VM specified by the given URI ID. |
| /r/v/servers/{server}/vms/{vm}/{action} | Executes an action on the VM specified by the given URI ID. |
| /r/v/servers/{server}/hosts/{host}/vms/{vm}/{action} | Executes an action on the VM specified by the given URI ID. |
For a full list of supported actions please see the UVAPI source code file VirtPowerOps.java.
Task URIs
These are the URIs used to retrieve information about tasks. Note that it is not possible to enumerate tasks, only retrieve them directly by their URI ID.
| /r/v/tasks/{task} | This URI retrieves the task specified by the given URI ID. |
URI IDs
In order to keep track of all of the objects that Vanagea accesses on different hypervisors, Vangaea refers to them by their unique IDs as the specific hypervisor implementation defines them. However, because these unique IDs must be transmitted by the client to Vangaea they are inevitably going to appear in the RESTful URIs that Vangaea makes use of. There is a slight problem with this as the format for a unique ID changes between different hypervisors. In order to normalize the appearance of URIs, I created the concept of a URI ID.
URI ID Format
A URI ID is a three to four character long string of alpha-numeric characters. It is generated by taking the hypervisor-specific unique ID of an object and creating a CRC-16 hash of it and then transforming that into a hexidecimal formatted string.
This is obviously a one-way transformation which is why the Vangaea database has a table for caching URI ID mappings. This way when an object is accessed with its URI ID, it is possible to retrieve the server the object is associated with as well as its original unique ID. For more information on the URI mapping table please see the document on Vangaea's database architecture.
Query Options
The data retrieved by the URIs can also be manipulated by a series of query string options:
Properties
p=propName1[,propName2,propName3,...propNameN-1]
Using the p query option, a user can request that objects are returned with given properties. By default Vangaea only returns an object's URI ID and name. This is because property retrieval can be a fairly expensive operation. For example, to retrieve a VM's current CPU usage the query string would be:
p=cpu
To retrieve a VM's CPU usage and its status the query string would be:
p=cpu,status
For a full list of supported properties please see the UVAPI source code file VirtProperties.java.
Output Format
f=json|xml
You can also control the output format of retrieved data using the f query option. Specify json to get the data back in JSON format and xml for data formatted as XML.
JSON is the default output format if no other format is explicitly specified.
Include Nulls
in
When JSON is the output format, properties with NULL values are not serialized as part of the result. You can change this behavior by specifying the query option in in the request URI.
Include Transients
it
By default, properties marked with the @Transient annotation are not serialized. You can change this behavior by specifying the query option it in the request URI.