Please note that these Trac pages are no longer being updated. Wiki contents/documentation have moved to GitHub.

Version 30 (modified by jsamuel, 10 years ago)

--

XML-RPC API to SeattleGENI


An XML-RPC interface to SeattleGENI is available, for clients wishing to access SeattleGENI functionality without going through the SeattleGENI website.
The XML-RPC server is located at https://seattlegeni.cs.washington.edu/xmlrpc/.
For examples on how to use XML-RPC with SeattleGENI, check out the  SeattleGENI XMLRPC Client Library.


Authentication

In order to talk with SeattleGENI over XML-RPC, authentication is required.
The authentication structure takes the form of the following dictionary:

{'username':'YOUR_USERNAME', 'api_key':'YOUR_API_KEY'}

The value of YOUR_USERNAME is the same username you use to login to the SeattleGENI website. The value of YOUR_API_KEY is the API key you can find on SeattleGENI when viewing the profile page for your account.

This structure is expected as the first argument in every XML-RPC API call.
All XML-RPC functions will return an XMLRPC Fault Code 101 if authentication fails.


XML-RPC Faults

In the event of an exception/error, an XML-RPC Fault will be sent to the client.
The fault code and message contains information about the error that occurred.


acquire_resources(auth, rspec)


Given a resource specification as a dict (rspec), this function acquires resources for the user. There are currently four types of rspecs defined:

{'rspec_type':'lan', 'number_of_nodes':N}
Acquire N vessels on nodes all with the same starting three octects of the IP address.

{'rspec_type':'wan', 'number_of_nodes':N}
Acquire N vessels on nodes all with different starting three octects of the IP address.

{'rspec_type':'nat', 'number_of_nodes':N}
Acquire N vessels on NAT nodes (nodes which are communicated with through a NAT forwarder).

{'rspec_type':'random', 'number_of_nodes':N}
Returns N vessels on any types of nodes, including a combination of different types of nodes.

Returns a list of dictionaries, where each dictionary contains information about an acquired vessel. The dictionaries are of the form:

{'node_ip':node_ip, 'node_port':node_port, 'vessel_id':vessel_id, 'node_id':node_id, 'handle':handle, 'expires_in_seconds':seconds}
node_ip is a string containing the IP or other identifying information of the node manager.
node_port is an integer representing the port used by the node manager.
vessel_id is a string which represents the vessel_id for the vessel (such as 'v21').
node_id is the node id of the node (a public key string).
handle has an undefined type but is used in future calls to release_resources. Make no assumptions about the type of this item.
expires_in_seconds is an integer representing the number of seconds until this vessel's acquisition will expire.

Raises an XMLRPC Fault Code 1 or 100 if an internal error occurred in SeattleGENI.
Raises an XMLRPC Fault Code 101 if authentication failed.
Raises an XMLRPC Fault Code 102 if any arguments were invalid.
Raises an XMLRPC Fault Code 103 if the account doesn't have enough credits available to acquire the requested vessels.
Raises an XMLRPC Fault Code 105 if SeattleGENI could not fulfill the request (e.g. there are not enough vessels of the requested type available).


acquire_specific_vessels(auth, vesselhandle_list)


Acquires specific vessels (vessels of specific names on specific nodes). This will be best effort. Zero or more of the vessels may be acquired. Requesting vessels that exist but are not available will not result in an exception.

The vesselhandle_list is a list of vessel handles.

Returns a list of dictionaries like that returned by acquire_resources.

Raises an XMLRPC Fault Code 1 or 100 if an internal error occurred in SeattleGENI.
Raises an XMLRPC Fault Code 101 if authentication failed.
Raises an XMLRPC Fault Code 102 if any arguments were invalid.
Raises an XMLRPC Fault Code 103 if the account doesn't have enough credits available to acquire the requested vessels.


release_resources(auth, list_of_handles)


Release resources (vessels) previously acquired by the account. The handles in list_of_handles indicate the vessels to be released.

Raises an XMLRPC Fault Code 1 or 100 if an internal error occurred in SeattleGENI.
Raises an XMLRPC Fault Code 101 if authentication failed.
Raises an XMLRPC Fault Code 102 if any arguments were invalid.


renew_resources(auth, list_of_handles)


Renew resources (vessels) previously acquired by the account. The handles in list_of_handles indicate the vessels to be renewed. Vessels are renewed for 7 days.

Raises an XMLRPC Fault Code 1 or 100 if an internal error occurred in SeattleGENI.
Raises an XMLRPC Fault Code 101 if authentication failed.
Raises an XMLRPC Fault Code 102 if any arguments were invalid.
Raises an XMLRPC Fault Code 103 if the account doesn't have enough credits available to renew any of its acquired vessels. This can happen, for example, if the account acquired vessels based on donations that have since gone offline resulting in the account being over its vessel credit limit.


get_resource_info(auth)


Returns a list of resources (vessels) currently acquired by the user.

The return list is of the same form as returned by acquire_resources.

Raises an XMLRPC Fault Code 1 or 100 if an internal error occurred in SeattleGENI.
Raises an XMLRPC Fault Code 101 if authentication failed.
Raises an XMLRPC Fault Code 102 if any arguments were invalid.


get_account_info(auth)


Returns a dictionary of account information for the account. This includes the user's port number, name, total number vessels that can be acquired, and the user's affiliation.

Returns a dictionary of the form:

{'user_port':user_port, 'user_name':user_name, 'urlinstaller':urlinstaller, 'private_key_exists':private_key_exists, 'max_vessel':max_vessel, 'user_affiliation':user_affiliation}
user_port is an integer, indicating a port number that by default will be available for TCP / UDP on all of the user's vessels.
user_name is a string containing the username.
max_vessel is an integer, indicating the total vessels allowed. This may vary as donations are credited to the user or go offline.
user_affiliation is a string and represents the affiliation provided by the user when registering for an account. This field is not validated so should not be trusted.

Raises an XMLRPC Fault Code 1 or 100 if an internal error occurred in SeattleGENI.
Raises an XMLRPC Fault Code 101 if authentication failed.
Raises an XMLRPC Fault Code 102 if any arguments were invalid.


get_public_key(auth)


Returns the user's public key as a string.

Raises an XMLRPC Fault Code 1 or 100 if an internal error occurred in SeattleGENI.
Raises an XMLRPC Fault Code 101 if authentication failed.
Raises an XMLRPC Fault Code 102 if any arguments were invalid.


get_encrypted_api_key(username)


Returns the user's api key encrypted with the user's public key.

Raises an XMLRPC Fault Code 1 or 100 if an internal error occurred in SeattleGENI.
Raises an XMLRPC Fault Code 102 if any arguments were invalid.