Version 3 (modified by 12 years ago) (diff) | ,
---|
- GENI Aggregate Manager API Version 2 Details
GENI Aggregate Manager API Version 2 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 2.
For an overview of this version of the AM API, see the API Version 2 overview page.
See Also:
- API Version 2 overview 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
GetVersion Details
Get static version and configuration information about this aggregate.
struct GetVersion([optional: struct options])
For a summary of the method signature and return, see the AM API overview page.
A sample GetVersion return:
{ 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> }
Arguments
options
- A struct with particular semantics described below. For this method only, this argument is optional. Aggregates should document new options arguments.
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.{ int geni_api; struct geni_api_versions { URL <this API version #>; # value is a URL, name is a number [optional: other supported API versions and the URLs where they run] } array geni_request_rspec_versions of { string type; string version; string schema; string namespace; array extensions of string; }; array geni_ad_rspec_versions of { string type; string version; string schema; string namespace; array extensions of string; }; }
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 |
Members of the GetVersion value
return struct
As elsewhere, implementations can add additional members to the return struct (at the top-level or within the value
return) as desired. The prefix geni_
is reserved for members that are part of this API specification. Implementations should choose an appropriate prefix to avoid conflicts. Aggregates should document any additional return values.
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
List the resources at this aggregate in an RSpec: may be all resources, only those available for reservation, or only those already reserved for the given slice.
struct ListResources(string credentials[], struct options)
For a summary of the method signature and return, see the AM API overview page.
Arguments
credentials[]
- An array of credentials with particular semantics.
options
- An XML-RPC struct containing members indicating the set of resources that the caller is interested in, or the format of the result. Semantics of this argument are described below. Aggregates should document new options arguments.
The following members are available for use in the options
parameter. All aggregate managers are required to implement these options.
{ boolean geni_available; boolean geni_compressed; string geni_slice_urn; struct geni_rspec_version { string type; string version; }; }
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_slice_urn
- Optional. An XML-RPC string indicating that the caller is interested in the set of resources allocated to the slice named by this URN. If no resources are allocated to the indicated slice by this aggregate, an empty RSpec should be returned -- aggregates should NOT return an error. For details on GENI AM API URN identifiers, see the GENI wiki page.
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. The contract for RSpec versions is described with links to further reading below.
The return value is an RSpec in text format if
geni_compressed
is unspecified or set tofalse
. The return value will be a base 64 encoded string ifgeni_compressed
is specified and set totrue
.
The returned Rspec will be an Advertisement RSpec when no
geni_slice_urn
option is supplied. When a validgeni_slice_urn
option is supplied, the returned RSpec will be a Manifest RSpec of the type corresponding togeni_rspec_version
, but in manifest format.
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 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 |
CreateSliver Details
Reserve the resources described in the given RSpec for the given slice, returning a manifest RSpec of what has been reserved.
struct CreateSliver(string slice_urn, string credentials[], string rspec, struct users[], struct options)
For a summary of the method signature and return, see the AM API overview page.
Arguments
slice_urn
-
The URN of the slice to which the resources specified in
rspec
will be allocated. For details on GENI AM API URN identifiers, see the GENI wiki page.
credentials
- An array of credentials with particular semantics. Aggregates should ensure that the expiration time of the reservation does not exceed the expiration time of the slice credential used to perform this operation.
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
).
users
-
An array of user structs, which contain information about the users that might login to the sliver that the AM needs to know about. Aggregates accepting this option for a resource are expected to install all supplied SSH keys - creating separate login accounts for each supplied user if possible. Each struct must include the key 'keys', which is an array of strings and can be empty. The struct must also include the key 'urn', which is the user’s URN string. The users array can be empty. For example:
[ { urn: urn:publicid:IDN+geni.net:gcf+user+alice keys: [<ssh key>, <ssh key>] }, { urn: urn:publicid:IDN+geni.net:gcf+user+bob keys: [<ssh key>] } ]
options
- A struct with particular semantics described below. Aggregates should document new options arguments.
Return
CreateSliver reserves the requested resources if possible. The aggregate then (asynchronously) starts those resources. The CreateSliver method returns a manifest RSpec.
CreateSliver 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
- The return value is an RSpec matching the GENI standard manifest RSpec schema listing and describing the resources that were allocated to the slice. The result RSpec may contain additional information about the allocated resources, such as specific resource identifiers and addresses. This RSpec should include a listing of the specific resources used to satisfy the reservation, and details on the configuration and address of these resources, to the extent that this information is known when completing the reservation and before the resources are fully instantiated. Such information which changes as the resources are made available for use (started) or such information which is only known when the resources have fully started, may be returned later by SliverStatus. Note that aggregates should preserve in the manifest RSpec any extensions supplied in the request RSpec which they do not understand.
If an Aggregate advertises a type
/version
pair in its geni_request_rspec_versions
as returned by GetVersion, then it promises to correctly honor a CreateSliver call containing a request RSpec in the given format, and then to return a Manifest RSpec in the corresponding format (ie a GENI v3 standard request is answered with a GENI v3 manifest).
The contract for RSpec versions is described with links to further reading below.
CreateSliver 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 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 |
DeleteSliver Details
Delete the reservation for this slice.
struct DeleteSliver(string slice_urn, string credentials[], struct options)
For a summary of the method signature and return, see the AM API overview page.
Arguments
slice_urn
- The URN of the slice whose sliver should be deleted. For details on GENI AM API URN identifiers, see the GENI wiki page.
credentials
- An array of credentials with particular semantics.
options
- A struct with particular semantics described below. Aggregates should document new options arguments.
Return
DeleteSliver stops all the slice's resources and removes the reservation. It returns true
or false
indicating whether it did this successfully. This API does not specify the state of the resources on error or failure.
DeleteSliver 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
-
Returns
true
on success andfalse
on failure.true
means all resources associated with this slice have been stopped and de-allocated. Behavior onfalse
is not specified.
DeleteSliver 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 |
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 |
SliverStatus Details
Get the status of the reservation for this slice at this aggregate.
struct SliverStatus(string slice_urn, string credentials[], struct options)
For a summary of the method signature and return, see the AM API overview page.
Arguments
slice_urn
- The URN of the slice for which the sliver status is requested. For details on GENI AM API URN identifiers, see the GENI wiki page.
credentials
- An array of credentials with particular semantics.
options
- A struct with particular semantics described below. Aggregates should document new options arguments.
Return
Return the status of the overall reservation, and of each addressable resource within the reservation. Additionally, provide any other aggregate or resource specific dynamic state or configuration information necessary for client use of the reserved resources.
SliverStatus 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
- Returns an XML-RPC struct upon successful completion. The struct is of the following form:
{ geni_urn: <sliver URN> geni_status: ready geni_resources: [ { geni_urn: <resource URN> geni_status: ready geni_error: ''}, { geni_urn: <resource URN> geni_status: ready geni_error: ''} ] }
SliverStatus 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 |
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 |
Members of the SliverStatus value
return struct
As elsewhere, implementations can add additional members to the return struct as desired to provide aggregate or resource specific status information. Specifically, information on accessing the resources, and expiration times for reservations might be returned. The prefix geni_
is reserved for members that are part of this API specification. Implementations should choose an appropriate prefix to avoid conflicts. Aggregates should document any additional return values.
The top level members of the returned value
struct pertain to the sliver as a whole. These members are:
geni_urn
- The URN of the sliver as a string. This is the sliver and not the slice, and should be selected by the aggregate manager. For details on GENI AM API URN identifiers, see the GENI wiki page.
geni_status
-
A string indicating the status of the sliver. Possible values are:
configuring
,ready
,failed
, andunknown
.configuring
indicates that at least one resource is being configured and none have failed.ready
indicates that all resources in the sliver are ready.failed
indicates that at least one resource in the sliver has failed.unknown
indicates that the state of the sliver is not one of the known states. More detailed information can be found in the value of thegeni_resources
member.
geni_resources
- An array of structs. Each struct in the array gives the status of one resource in the sliver. The members of these structs are described below.
The members of the geni_resources
struct(s) are as follows:
geni_urn
- The URN of the resource as a string. This is specific to the sliver, and should be selected by the aggregate manager to allow status reporting and control at the finest level supported at that aggregate. It may be a sliver URN if there is only 1 resource in the sliver.
geni_status
-
A string indicating the status of the resource. Possible values are:
configuring
,ready
,failed
, andunknown
.configuring
indicates that the resource is being configured and is not yet ready for use.ready
indicates that the resource is ready.failed
indicates that the resource has failed.unknown
indicates that the state of the resource is not one of the known states.
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
.
RenewSliver Details
Renew the reservation for resources in this slice.
struct RenewSliver(string slice_urn, string credentials[], string expiration_time, struct options)
For a summary of the method signature and return, see the AM API overview page.
Arguments
slice_urn
- The URN of the slice that is to have its sliver renewed. For details on GENI AM API URN identifiers, see the GENI wiki page.
credentials
- An array of credentials with particular semantics.
expiration_time
- A string in RFC 3339 format indicating the new reservation expiration date and time desired by the caller. Note that these times, per the RFC, must be in or relative to UTC. This time must be less than or equal to the slice duration in the slice credential. In other words, at least one supplied (slice) credential must still be valid at the desired new expiration time for this call to succeed.
options
- A struct with particular semantics described below. Aggregates should document new options arguments.
Return
Return true
or false
indicating whether the reservation was successfully extended to the requested date and time.
RenewSliver 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
-
Returns
true
on successful completion,false
otherwise.false
means the reservation expires at the previous time. It is assumed that the caller will have already extended the lifetime of the slice credential with the appropriate slice authority prior to calling RenewSliver.
RenewSliver 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 |
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 |
Shutdown Details
Perform an emergency shutdown of the resources in a slice at this aggregate.
struct Shutdown(string slice_urn, string credentials[], struct options)
For a summary of the method signature and return, see the AM API overview page.
Arguments
slice_urn
- The URN of the slice that is to have its sliver shut down. For details on GENI AM API URN identifiers, see the GENI wiki page.
credentials
- An array of credentials with particular semantics.
options
- A struct with particular semantics described below. Aggregates should document new options arguments.
Return
Returns a boolean indicating whether the resources associated with this reservation were successfully shut down to a state suitable for forensics.
Shutdown 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
-
Returns
true
on success,false
otherwise. On success, the resources should no longer be accessible to the client nor in a running state. On failure, state is indeterminate.
Shutdown 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 |
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.
RSpecs
At GEC10 the GENI community agreed that GENI RSpecs would be in what was the ProtoGENI v2 format and is now known as GENI v3. Aggregates are free to use an alternate format internally, but must accept and produce compliant RSpecs on demand. Note that individual aggregates may use RSpec extensions to describe custom resources or properties of resources. For RSpec extension information, see the ProtoGENI wiki.
For more information:
- Official GENI v3 RSpec schemas
- GENI standard (was ProtoGENI v2) format
- RSpec extension information
- RSpec schemas listing
The Aggregate Manager API requires this contract:
Aggregates advertise the type
and version
of RSpec formats that they support. If available, they specify the schema
, namespace
and extensions
combination which is the authoritative definition of that format. Clients of the API should understand that combination in order to know how to understand the resources available at that aggregate.
If an aggregate advertises a particular type
/version
(optionally defined with a combination of schema
, namespace
and extensions
) in the geni_ad_rspec_versions
attribute of GetVersion, then it promises to send a correct Advertisement RSpec in response to a ListResources call which supplies a geni_rspec_version
option containing that type
/version
. (geni_rspec_version
is a struct
with 2 members, type
and version
. type
and version
are case-insensitive strings, matching those in geni_ad_rspec_versions
).
If an Aggregate advertises a particular type
/version
(optionally defined with a combination of schema
, namespace
and extensions
) in the geni_request_rspec_versions
attribute of GetVersion then it promises to correctly honor a CreateSliver call containing a request RSpec in the given format, and then to return a Manifest RSpec in the corresponding format (i.e. a GENI format request is answered with a GENI format manifest). The aggregate also promises to send a correctly formatted Manifest RSpec in response to a ListResources call which supplies a valid geni_slice_urn
option and an geni_rspec_version
option containing that supported type
/version
.
credentials
Argument
credentials
-
An array of credentials. At least one credential must be a valid slice credential for the slice specified in
slice_urn
if that is an argument, or a valid administrative credential with sufficient privileges. Credentials must be valid (signed by a valid GENI certificate authority either directly or by chain, not expired, and grant privileges to the client identified by the SSL client certificate). Each method requires specific privileges, which must be granted by the provided credentials. Note that the semantics of this argument is not clear: most implementations require a single credential to provide all needed privileges. Alternative interpretations might, for example, accumulate privileges from each valid credential to determine overall caller permissions. For details on GENI AM API format credentials, see the GENI wiki.
options
options
-
An XML-RPC struct. For GetVersion only, this argument is optional. In all other methods, it is required. Only ListResources has required entries in the
options
struct. Aggregates are compliant with this API change by accepting this argument. Aggregates may accept entries to this struct. Aggregates should not require any new options to any method - they should always have a reasonable default for any such option. Aggregates should document new options arguments. The prefixgeni_
is reserved for members that are part of this API specification. Implementations should choose an appropriate prefix to avoid conflicts.
Return Struct
code
, value
, and output
together provide the standard return from all AM API methods.
code
-
A struct indicating the success or failure of this call at the Aggregate Manager. It consists of 1 required field and 2 optional fields.
struct code = { int geni_code; [optional: string am_type;] [optional: int am_code;] }
value
- Method-specific. Required on success. Optional on error.
output
- On failure or error, this is required. Optional on success. This is an XML-RPC string with a human readable message explaining the result. Specifically, this might include an error string, a stacktrace, or other useful messages to help the experimenter resolve or report the failure or error. It is not defined on success, though aggregates are free to use it.
Implementations can add additional members to the return struct as desired. The prefix geni_
is reserved for members that are part of this API specification. Implementations should choose an appropriate prefix to avoid conflicts. Aggregates should document any additional return values.
Aggregates shall return consistent values for geni_code
as described here. Aggregates wishing to be more specific may use the am_type
and am_code
values.
Success is always indicated using a geni_code
value of 0
.
On one of the error or failure cases listed in the table below, aggregates shall return the indicated error code.
Elements in code
geni_code
-
An integer supplying the GENI standard return code indicating the success or failure of this call. Error codes are standardized and defined in the attached XML document. Codes may be negative. A success return is defined as
geni_code
of0
.
am_type
-
Optional. A (case insensitive) string indicating the type of Aggregate Manager running locally. When an aggregate wants to return an aggregate specific return code in the
am_code
field, they supply anam_type
to qualify the kind of aggregate specific return code they are supplying. This is the namespace of the aggregate specific return code. This field is optional: aggregates are not required to supply an aggregate specific return code, and clients need not look at it. This code further qualifies the kind of error or success that the aggregate is returning, as primarily defined by the value ofgeni_code
. Standard values foram_type
are defined in the attached XML document. am_code
-
An integer supplying the more specific return code, relative to the aggregate type specified in
am_type
. This integer may be negative. Aggregates should document these codes publicly. This API does not specify how or where that documentation should be provided.
Aggregates are encouraged to use code
values and output
messages that help experimenters and tools distinguish between bad input, other experimenter error, temporary server errors, or server bugs.
GENI standard error codes are documented in the attached XML document, and listed below.
0 | SUCCESS | "Success" |
1 | BADARGS | "Bad Arguments: malformed arguments" |
2 | ERROR | "Error (other)" |
3 | FORBIDDEN | "Operation Forbidden: eg supplied credentials do not provide sufficient privileges (on given slice)" |
4 | BADVERSION | "Bad Version (eg of RSpec)" |
5 | SERVERERROR | "Server Error" |
6 | TOOBIG | "Too Big (eg request RSpec)" |
7 | REFUSED | "Operation Refused" |
8 | TIMEDOUT | "Operation Timed Out" |
9 | DBERROR | "Database Error" |
10 | RPCERROR | "RPC Error" |
11 | UNAVAILABLE | "Unavailable (eg server in lockdown)" |
12 | SEARCHFAILED | "Search Failed (eg for slice)" |
13 | UNSUPPORTED | "Operation Unsupported" |
14 | BUSY | "Busy (resource, slice); try again later" |
15 | EXPIRED | "Expired (eg slice)" |
16 | INPROGRESS | "In Progress" |
17 | ALREADYEXISTS | "Already Exists (eg the slice}" |
Aggregates are similarly encouraged to provide hints on how to fix bad requests using the value
entry to experimenters on error or failures. For example, a failed RenewSliver call that failed because you are not allowed to renew your sliver that far in the future, might return a new date string in the value
field that would be allowed. Similarly, a failed CreateSliver call might return a modified request RSpec in the value
field.
Note that a malformed XML-RPC request should still raise an XML-RPC Fault, and other Faults dictated by the XML-RPC specification should still be raised. Aggregates should avoid raising an error (XML-RPC Fault) for application layer errors or any other cases where the XML-RPC specification does not require a Fault, but rather should attempt to return this struct, providing any error messages and stack traces in the output
field or other additional fields. Certain XML-RPC errors may be returned using Faults or otherwise by the XML-RPC layer, or may more properly be returned using this struct in the application layer. In such cases, servers should use error codes with negative values. Selected such errors are listed below:
-32001 | SERVERBUSY | "Server is (temporarily) too busy; try again later" |
Note also that servers may respond with other HTTP error codes, and clients must be prepared to deal with those situations. Specifically, a server that is busy might return HTTP code 503, or just refuse the connection.
Documenting Aggregate Additions
Aggregates are free to add additional return values or input options
to support aggregate or resource specific functionality, or to innovate within the bounds of the AM API. Aggregates are encouraged to document any such new return values which they return or options
arguments, to bootstrap coordination with clients, and provide documentation for human experimenters. One way to provide partial documentation, is to implement XML-RPC introspection. Through the use of method help, aggregates can provide human readable text describing return values. Alternatively or additionally, aggregates may document return values as part of their return from GetVersion. This API does not specify the format for advertising those extra return values in GetVersion.
Supporting Multiple API Versions
Aggregates are free to support multiple versions of the AM API. They do so by providing different URLs for each version of the API that they support. Aggregates should have a 'default' URL (the one typically advertised). That version runs whichever version of the API the server chooses (could be the latest, could be something else.)
Aggregates running multiple versions of the API must advertise the URLs and versions of the API supported using the new GetVersion return as part of the value
entry:
geni_api_versions: an XML-RPC struct containing 1+ entries of: Name: Integer - supported GENI AM API version Value: String - URL to the XML-RPC server implementing that version of the GENI AM API
For example
geni_api_versions: { 1: <URL>, 2: <Local URL, as this is API version 2>, ... }
The entries indicate versions of the API that are supported, and URLs are absolute URLs where that version of the API is supported.
Attachments (2)
- geni-error-codes.xml (7.4 KB) - added by 11 years ago.
- geni-am-types.xml (1.6 KB) - added by 11 years ago.
Download all attachments as: .zip