wiki:DRAFT_GAPI_AM_API_V2_DETAILS

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

--

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:

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 minimal 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 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_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 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. 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 to false. The return value will be a base 64 encoded string if geni_compressed is specified and set to true.

The returned Rspec will be an Advertisement RSpec when no geni_slice_urn option is supplied. When a valid geni_slice_urn option is supplied, the returned RSpec will be a Manifest RSpec of the type corresponding to geni_rspec_version, but in manifest format.

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 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 of BADVERSION (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. 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 and false on failure. true means all resources associated with this slice have been stopped and de-allocated. Behavior on false 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, and unknown. 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 the geni_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, and unknown. 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:

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 prefix geni_ 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 of 0.
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 an am_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 of geni_code. Standard values for am_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)

Download all attachments as: .zip