wiki:GAPI_AM_API_V3_DETAILS

Version 2 (modified by Aaron Helsinger, 8 years ago) (diff)

--

GENI Aggregate Manager API Version 3 Details

The GENI Aggregate Manager API allows aggregates to advertise resources and to allocate resources to Slices in the form of Slivers.

This page provides details on GENI AM API Version 3.

For an overview of this version of the AM API, see the API Version 3 overview page.

See Also:

TBD: What goes here?

GetVersion Details

Sample output:

FIXME FIXME

{
  geni_api = 2 # This is AM API v2
  code = {
       geni_code = 0 # Success
       # am_type and am_code are optional. Leaving them out.
     }
  value = 
      {
        geni_api = 2 # Match above
        geni_api_versions = {
             2 = <This server's AM API absolute URL>
             # optional: 1 = <Some other URL for talking AM API v1 to the same aggregate
        }
        geni_request_rspec_versions = [{
             type = "GENI"
             version = "3"
             schema = "http://www.geni.net/resources/rspec/3/request.xsd"
             namespace = "http://www.geni.net/resources/rspec/3"
             extensions = ["http://hpn.east.isi.edu/rspec/ext/stitch/0.1/stitch-schema.xsd", <other URLs here>]
        }]
        geni_ad_rspec_versions = [{
             type = "GENI"
             version = "3"
             schema = "http://www.geni.net/resources/rspec/3/ad.xsd"
             namespace = "http://www.geni.net/resources/rspec/3"
             extensions = ["http://hpn.east.isi.edu/rspec/ext/stitch/0.1/stitch-schema.xsd", <other URLs here>]
        }]
      }
  output = <None>
}

Return

GetVersion returns the version of the Aggregate Manager API running locally, the RSpec schemas supported, and the URLs where versions of the AM API are running. The return is an XML-RPC struct whose members are described below.

geni_api
An integer indicating the revision of the Aggregate Manager API that an aggregate supports. This page documents version 2 of the API. This value is duplicated here and within the value return struct for backwards compatibility with AM API v1 clients.

code, value, and output together provide the standard return from all AM API methods, which has a specific structure and semantics described below, including specifics of the code and output members.

value
For GetVersion, value is an XML-RPC struct containing the actual return for the method. On success, this is required. Optional (and not defined) on failure or error.

GetVersion return codes

Aggregates shall return consistent values for geni_code as described here. Success is always indicated using a geni_code value of 0. On error, return the appropriate GENI error code in geni_code, as listed in this table. These error codes are part of a larger set of codes with specific meanings required by this API, described below.

Error Condition
ERROR Internal error
SERVERERROR Server error
geni_api
An integer indicating the revision of the Aggregate Manager API that an aggregate supports. This page documents version 2 of the API.
geni_api_versions
An XML-RPC struct indicating the versions of the Aggregate Manager API supported at this aggregate, and the URLs at which those API versions can be contacted. This element is required, and shall include at least 1 entry indicating the local aggregate manager URL and the version of the API supported at that URL. Aggregates supporting multiple versions of the Aggregate Manager API should conform to the guidelines specified below.
geni_api_versions: an XML-RPC struct containing 1+ entries of:
  Name: Integer - supported GENI AM API version
  Value: String - Absolute URL to the XML-RPC server implementing that version of the GENI AM API
geni_request_rspec_versions
An array of data structures indicating the RSpec types accepted by this AM in a request. The contract for RSpec versions is described with links to further reading below.
geni_ad_rspec_versions
An array of data structures indicating what types of RSpec advertisements may be produced by this AM in ListResources.

geni_request_rspec_versions and geni_ad_rspec_versions refer to the RSpec formats supported at this aggregate. The contract for RSpec versions is described with links to further reading below.

Elements used within geni_request_rspec_versions and geni_ad_rspec_versions:

type, version
Two case-insensitive strings which together comprise the type of RSpec. The RSpec type should be one of "geni", "protogeni", "sfa", "orca", "openflow", or "orbit". version should be a type-specific version identifier as specified by the appropriate control framework. The "geni" type is reserved for GENI standard format RSpecs, following the schemas hosted at http://www.geni.net/resources/rspec.
schema
An optional URL pointing to a schema which can be used to verify the given type of RSpec.
namespace
An optional XML namespace which the RSpec of the given type belongs to.
extensions
An array of aggregate-specific strings denoting which extensions are supported. In the case of GENI standard RSpecs, these are XML namespaces which denote the extension as a whole.

ListResources Details

geni_available
Optional. An XML-RPC boolean value indicating whether the caller is interested in all resources or available resources. If this value is true, the result should contain only available resources. If this value is false or unspecified, both available and allocated resources should be returned. The Aggregate Manager is free to limit visibility of certain resources based on the credentials parameter.
geni_compressed
Optional. An XML-RPC boolean value indicating whether the caller would like the result to be compressed. If the value is true, the returned resource list will be compressed according to RFC 1950. If the value is false or unspecified, the return will be text.
geni_rspec_version
Required. An XML-RPC struct indicating the type and version of Advertisement or Manifest RSpec to return. The struct contains 2 members, type and version. type and version are case-insensitive strings, matching those in geni_ad_rspec_versions as returned by GetVersion at this aggregate. This option is required, and aggregates are expected to return a geni_code of 1 ('Bad Arguments') if it is missing. Aggregates should return a geni_code of 4 (BADVERSION) if the requested RSpec version is not one advertised in GetVersion as supported. The contract for RSpec versions is described with links to further reading below.

Return

ListResources returns an RSpec listing and describing resources at this aggregate. Depending on the arguments, this may be all local resources, only available local resources, or a manifest of resources reserved for a particular slice.

ListResources returns the standard return from all AM API methods, which has a specific structure and semantics described below, including specific requirements for the code and output members.

value
ListResources returns an RSpec in GENI standard schema.

If the aggregate cannot support the requested type/version (that pair is not listed in geni_ad_rspec_versions), then the aggregate returns an error (geni_code) of 4 (BADVERSION), and the value is not defined.

ListResources return codes

On error, return the appropriate GENI error code in geni_code, as listed in this table. These error codes are part of a larger set of codes with specific meanings required by this API, described below.

Error Condition
BADARGS One of the required arguments is badly formed or missing
FORBIDDEN Credential does not grant permission to aggregate
ERROR Internal error
SERVERERROR Server error
UNAVAILABLE Unavailable (eg server in lockdown)
BADVERSION Bad Version of RSpec requested

Describe Details

Error Condition
BADARGS One of the required arguments is badly formed or missing
FORBIDDEN Credential does not grant permission to the slice
FORBIDDEN Slice has been shutdown by the Clearinghouse
BUSY Slice is temporarily locked, try again later
ERROR Internal error
SERVERERROR Server error
UNAVAILABLE Unavailable (eg server in lockdown)
EXPIRED Slice expired
BADVERSION Bad Version of RSpec requested

Allocate Details

rspec
An RSpec matching the GENI standard request RSpec schema containing the resources that the caller is requesting for allocation to the slice specified in slice_urn. These are expected to be consistent with the resources returned by a previous invocation of ListResources. If this RSpec is in a format not listed as supported by GetVersion, then the aggregate will return an error of BADVERSION (4).

FIXME: These same errors for Provision?

Error Condition
BADARGS One of the required arguments is missing or badly formed
FORBIDDEN Credential does not grant permission to the slice
FORBIDDEN Slice has been shutdown by the Clearinghouse
UNAVAILABLE AM is temporarily not allowing external users to create slices
ERROR Internal error
SERVERERROR Server error
BADVERSION Bad Version of RSpec requested

Renew Details

Error Condition
BADARGS One of the required arguments is badly formed or missing
SEARCHFAILED Slice does not exist at this AM
FORBIDDEN Credential does not grant permission to the slice
FORBIDDEN Slice has been shutdown by the Clearinghouse
BUSY Slice is temporarily locked, try again later
ERROR Internal error
SERVERERROR Server error
EXPIRED Resources already expired

Provision Details

Status Details

Error Condition
BADARGS One of the required arguments is badly formed or missing
SEARCHFAILED Slice does not exist at this AM
FORBIDDEN Credential does not grant permission to the slice
BUSY Slice is temporarily locked, try again later
ERROR Internal error
SERVERERROR Server error
UNAVAILABLE Unavailable (eg server in lockdown)
EXPIRED Slivers expired
geni_error
A free form string. The aggregate manager should set this to a string that could be presented to a researcher to give more detailed information about the state of the resource if its status is failed.

PerformOperationalAction Details

Delete Details

Error Condition
BADARGS One of the required arguments is badly formed or missing
SEARCHFAILED Slice does not exist at this AM
FORBIDDEN Credential does not grant permission to the slice
BUSY Slice is temporarily locked, try again later
ERROR Internal error
SERVERERROR Server error
EXPIRED Sliver(s) already expired and gone

Shutdown Details

Error Condition
BADARGS One of the required arguments is badly formed or missing
SEARCHFAILED Slice does not exist at this AM
FORBIDDEN Credential does not grant permission to the slice
ERROR Internal error
SERVERERROR Server error
EXPIRED Slice expired
INPROGRESS Shutdown in progress

Note: Aggregates should not return BUSY: this is a time critical operation that should succeed if possible.