What is the vappio API?

vappio is an API for the creation and manipulation of clusters on a cloud in a platform agnostic way. vappio was originally designed on top of EC2 so in some places it uses EC2 terminology but the functionality is more generic. As of this writing (Dec 6 2010) vappio works on EC2 and Nimbus based infrastructures.

This document provides the description of the API that a vappio implementation is expected to adhere. A command line and webservice based API is shown.

The command line API

The description of the command line tools detail the differences between them. Most of the tools share some functionality described here.

–host and –name

Almost all command line programs take a --host and --name option. Because the command line API is using the webservices in the background the host to connect to can be specified with --host. In many cases one wishes to specify a particular cluster to run a command on. For example if one has an EC2 cluster up and wants to add instances they would want to specify which cluster to add instances to. This is done through the --name option. These values default to localhost and local respectively.

The webservice API

All of the webservices use JSON as the language for communication. The documentation of the webservices include valid JSON input and the expected responses. Many of the webservice operations actually initiate long running jobs in which case a task id (which is a string) is returned. This task id can be queried using the tasks webservice API. Other webservices return more complicated data structures. The response from a webservice is always wrapped in a JSON dictionary that describes if the operation was a success or failure.

Response objects

All vappio webservice responses are a dictionary with the following attributes:

Parameter Type Meaning
success Boolean If true, the request was successfull and the data attribute contains the response. If false data contains failure information.
data Any On success this is whatever the API documentation describes the output to be. On failure it is an error object described below.

An error object:

Parameter Type Meaning
msg String A message describing the error.
name String The type or name of the error. This could be empty.
stacktrace String A stacktrace of the error if it can be determined. This could be empty.

Here is an example successful output from the list clusters API:

 "data": [
 "success": true

Here is an example failure output from the describe clusters API:

 "data": {
  "msg": "anycluster",
  "stacktrace": "Traceback (most recent call last):\n  File \"/opt/vappio-py/igs/cgi/\", line 56, in generatePage\n
body = cgiPage.body()\n  File \"/var/www/vappio/\", line 31, in body\n
cluster = cluster_ctl.loadCluster(request['name'])\n  File \"/opt/vappio-py/vappio/cluster/\", line 237, in loadCluster\n
cl = persist_mongo.load(name)\n  File \"/opt/vappio-py/vappio/cluster/\", line 55, in load\n
raise ClusterDoesNotExist(name)\nClusterDoesNotExist: anycluster\n",
  "name": "vappio.cluster.persist_mongo.ClusterDoesNotExist"
 "success": false

Table Of Contents

Previous topic


Next topic


This Page