Version 3 (modified by 12 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:
- API Version 3 overview page
- API Version 3 common concepts, arguments, and returns page
- GENI API implementation status
- GENI credentials for authorization
- GENI certificates for authentication. The GENI AM API uses XML-RPC over SSL with client authentication using certificates.
- Open issues with this API
- 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 = <This server's AM API absolute URL> 2 = <Prior API version still supported at a slightly different URL> } 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>] }] geni_credential_types = [{ geni_type = "SFA" geni_version = "1" }] geni_single_allocation = 0 # false - can operate on individual slivers geni_allocate = "geni_many" # Can do multiple Allocates } 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 isfalse
or unspecified, both available and allocated resources should be returned. The Aggregate Manager is free to limit visibility of certain resources based on thecredentials
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 isfalse
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
andversion
.type
andversion
are case-insensitive strings, matching those ingeni_ad_rspec_versions
as returned by GetVersion at this aggregate. This option is required, and aggregates are expected to return ageni_code
of1
('Bad Arguments') if it is missing. Aggregates should return ageni_code
of4
(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 ingeni_ad_rspec_versions
), then the aggregate returns an error (geni_code
) of4
(BADVERSION
), and thevalue
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 ofBADVERSION
(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.