[[PageOutline]] = 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 [wiki:GAPI_AM_API_V3 API Version 3 overview page]. See Also: * [wiki:GAPI_AM_API_V3 API Version 3 overview page] * [wiki:GAPI_AM_API_V3/CommonConcepts API Version 3 common concepts, arguments, and returns page] * [wiki:GeniApi GENI API] implementation status * [wiki:GeniApiCredentials GENI credentials] for authorization * [wiki:GeniApiCertificates GENI certificates] for authentication. The GENI AM API uses XML-RPC over SSL with client authentication using certificates. * [wiki:GAPI_AM_API_ISSUES Open issues with this API] * [wiki:GAPI_AM_API_DRAFT Draft API Revisions] proposed for future versions of this API ''' This page is a work in progress! ''' == !GetVersion Details == Sample output: '''FIXME FIXME''' {{{ { geni_api = 3 # This is AM API v3 code = { geni_code = 0 # Success # am_type and am_code are optional. Leaving them out. } value = { geni_api = 3 # Match above geni_api_versions = { 3 = 2 = } 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", ] }] 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", ] }] geni_credential_types = [{ # Accept only SFA style credentials for API v3 geni_type = "geni_sfa" geni_version = "3" }] geni_single_allocation = 0 # false - can operate on individual slivers geni_allocate = "geni_many" # Can do multiple Allocates } output = } }}} === 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 [#ReturnStruct standard return from all AM API methods], which has a specific [#ReturnStruct 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 [#ReturnStruct 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 [#SupportingMultipleAPIVersions 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 [#RSpecs 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 [#RSpecs 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 URL pointing to a schema which can be used to verify the given type of RSpec. May be empty. `namespace`:: An XML namespace which the RSpec of the given type belongs to. May be empty. `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. May be empty. ----- == !ListResources Details == `geni_available`:: Optional. An [http://www.xmlrpc.com/spec 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 [http://www.xmlrpc.com/spec 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 [http://www.ietf.org/rfc/rfc1950.txt RFC 1950]. If the value is {{{false}}} or unspecified, the return will be text. `geni_rspec_version`:: Required. An [http://www.xmlrpc.com/spec 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 [#RSpecs 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 [#ReturnStruct standard return from all AM API methods], which has a specific [#ReturnStruct 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 [#ReturnStruct 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 [http://www.protogeni.net/trac/protogeni/wiki/RSpec GENI standard] request RSpec [http://www.geni.net/resources/rspec/3/request.xsd 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 [wiki:GAPI_AM_API_V3#ListResources 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.