Class Overview

The GENI Clearinghouse API consists of a series of services provided by a series of service providers, namely:

• Authorization Service: Provides services for authorizing particular actions by particular users in certain contexts based on their identity, roles and privileges
• Logging Service: Provides services to log and retrieve tagged information about critical events, e.g. aggregate interactions, slice, member, project modifications, etc.
• Member Authority: Provides services regarding membership of GENI experimenters including their roles, privileges, account status, credentials, key materials. Note: it is from the Member Authority that experimenters get a GENI account and credentials for interacting with other services.
• Project Authority: Provides services regarding management of projects and project membership
• Service Registry: Provides lists of service providers (of the kinds described here) registered within the GENI Clearinghouse
• Slice Authority: Provides services regarding management of slices and slice membership and credentials

A client of a GENI CH API queries the Service Registry for service providers of particular types. The Service Registry is accessed by a known static URL. The client then forms a message, described under 'Message_Structure', sends it via HTTPS to the given server and receives a response, described under 'Return_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:

• "operation" : the name of the API method to be invoked

The user then adds any name/value pairs required for that particular method invocation.

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.

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:

• PROJECT=1: Refers to a specific project and takes a context_id (i.e. the project's UUID)
• SLICE=2: Refers to a specific slice and takes a context_id (i.e. the slice's UUID)
• RESOURCE=3: Refers to the ability to take actions that manage resources (e.g. creating a project)
• SERVICE=4: Refers to the ability to change the set of services provided by the Clearinghouse (those in the Service Registry, e.g.)
• MEMBER=5: Refers to the abilitiy to change the account information about GENI members

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:

• LEAD=1: The lead or owner of a project or slice. There can be only one of these per project/slice. They are the person responsible and principal point-of-contact regarding all activity on that project or slice
• ADMIN=2: A person with privileges to change attributes or privileges of other members of a group, but not the lead.
• MEMBER=3: A normal member of a group with privileges to normal (typically read and write) operations on entities managed by that group.
• AUDITOR=4: A member of the group with read-only privileges.

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)

All method calls from the GENI CH API return a dictionary representing a 3-tuple of values:

• "code" : the error code, if any (0 if no error)
• "value" : the result value, only valid if "code" is 0. This is the value indicated as the 'return' for all documented functions
• "output" : the error detail (typically a descriptive string) associated with an invocation error (i.e. error is not 0)