ApiUsage

API Usage

ToMaTo offers an XML-RPC API that can be used to control topologies. The web-frontend also uses this API, so everything that is possible in the web-frontend is also possible via the API. The API even offers somec features like executing commands on openvz devices that are not available in the web-frontend.

Tho API can be used with the client library that can easily be used interactively, scripted, or embedded into another application.

The python client library

The client library can be downloaded directly from the source code (development version, stable version). The client library can either be used as a library to establish a connection to the API or it can be executed directly as a command-line client.

The command-line client

The command-line client accepts the following parameters:

usage: tomato.py [-h] --hostname HOSTNAME [--port PORT] [--ssl]
                 [--username USERNAME] [--password PASSWORD] [--file FILE]
                 [arguments [arguments ...]]

The German-Lab ToMaTo API server runs on tomato.german-lab.de on port 8000 and uses SSL so the call should be tomato.py --hostname master.tomato-lab.org --port 8001 --ssl

It offers a python shell, where all API functions can be accessed as global functions.

To see a list of available commands, type help(). To see the documentation of a certain command, type help(command)

The python library

The library is contained in the lib folder. In order to access the API, a ServerProxy object has to be created using the getConnection function. All available API commands can then be called as methods on this object:

from lib import getConnection
api = getConnection(hostname, port, ssl, username, password, client_cert) #username, password and client_cert are all optional, but either username and password or client_cert have to be provided.
print api.account_info()

API documentation

Good examples how to use the API can be obtained from the test cases. More information about the API can be found in the APIDocumentation.

Understanding the API

The API uses RPC, which means that it uses imperative syntax.

It offers access to objects of different classes:

• account
• topology
• element
• connection
• host
• site
• organization (and others)

Objects are referenced by a unique ID.

Every of these classes has different methods, usually they are:

• create (class method)
• list (class method)
• remove (object method)
• info (object method)
• modify (object method)
• action (object method, only available for topology, element, and connection objects to change their state)

API commands are usually of the form [class]_[command], for example topology_list Thus, to get a list of all topologies, call topology_list()

In order to call a method on an object, you have to pass its ID as the first parameter. I.e., to call the info method on a topology object, call topology_info(id). The create method usually returns the ID of the newly created object, and the ID is included in result lists. The ID of an object cannot be changed.

The modify method usually takes an argument called attrs, which can be understood as a dictionary which overwrites values which are returned by the info method. I.e., if site_info returns

>>>site_info('ukl')
{'geolocation': {'latitude': 49.4400657, 'longitude': 7.7491265}, 
'description': 'TU Kaiserslautern', 
'location': 'Germany', 
'description_text': 'University of Kaiserslautern', 
'organization': 'ukl', 
'name': 'ukl'}

and you want to change some values, you can call

site_modify('ukl',
            {   'description': 'Technische Universität Kaiserslautern',
                'location': 'Kaiserslautern'
            }
           )

You should check the exact arguments and their meaning in the API documentation, since some methods require or support additional parameters.