Class Overview
This documents the GENI Clearinghouse API essentials: how methods are invoked, the return values and the authorization and validation of the calls.
public
|
#
Service_Flow( )
The GENI Clearinghouse API consists of a series of services provided by a series
of service providers, namely:
|
public
|
#
Message_Structure( )
All CH API calls are fundamentally posting S/MIME messages to the appropriate
service URL. The message should contain a dictionary consisting of key/value
pairs. This pair is mandatory:
For example, to invoke the 'lookup_slice' method, the user creates a dictionary with the keys 'operation'=>'lookup_slice', 'slice_id'=> $slice_id. That dictionary is put in an S/MIME message signed with the private key of the requestor, JSON encoded and posted via HTTPS to a 'slice authority' server whose URL is found in the Clearinghouse Service Registry. On the server, the message signature is retrieved and the public key of the user is used to validate the signature of the message. If validated, the message is JSON decoded and the argument dictionary is extracted. An authorization step is then invoked to determine if the given user has the privilege to invoke the given method, possibly in the particular (e.g. slice or project) context. If the message is not validated, or the invocation is not authorized, a response is generated as an error message indicating that reason. If the invocation is authorized, the 'operation' field in the dictionary of the message is used to dispatch the message appropriately. The service method then receives the full dictionary as given in the message, and the function generates a response as documented in these API pages. The response is then JSON encoded and S/MIME signed with the server's private key and returned to the requestor via HTTPS. |
public
|
#
Argument_Types( )
The GENI Clearinghouse API contains services whose arguments are often one of
these types:
Context: Methods that call for a "Context" and "ContextID" argument reflect the relationship of a principal to a particular object. Specifically, privileges of GENI members may be provided and tested on the granularity of a context. For some context_types, there is a specific context_id required, indicating a context of a particular object (e.g. a specific slice or project). Other context types, as noted, are not applied to a particular context_id. These are the context_types recognized by GENI:
Role_Types: Calls specifying a 'role_type' require an indication of the role a given member plays within a group (e.g. a slice or project). Privileges are often allotted to members based on their role within a group. The set of roles recognized in the GENI CH API are:
Attributes: Many objects are tagged with dictionaries of name/value pairs for later query (by explicit match on a single attribute, or by "AND" of a dictionary of attributes or by "OR" of "AND" of a list of dictionaries of attributes) |
public
|
#
Return_Structure( )
All method calls from the GENI CH API return a dictionary representing a 3-tuple
of values:
|