Changes between Initial Version and Version 1 of DRAFT_GAPI_AM_API_V2_DETAILS

Timestamp:

12/02/11 17:45:00 (12 years ago)

Author:

Aaron Helsinger

Comment:

--

DRAFT_GAPI_AM_API_V2_DETAILS

@@ +1 @@
+[[PageOutline]]
+= 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. A Sliver is the set of resources allocated by one Aggregate to one Slice.
+
+This page provides details on GENI AM API Version '''2'''.
+
+For an overview of this version of the AM API, see the [wiki:SW_AMAPI_V2_Take2 API Version 2 overview page].
+
+See Also:
+ * [wiki:DRAFT_GAPI_AM_API_V2 API Version 2 overview 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:DRAFT_GAPI_AM_API_ISSUES Open issues with this API]
+ * [wiki:DRAFT_GAPI_AM_API_DRAFT Draft API Revisions] proposed for the next version 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 [wiki:DRAFT_GAPI_AM_API_V2#GetVersion 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`::
+     [#Options A struct with particular semantics described below].  For this method only, this argument is optional. Aggregates should [#DocumentingAggregateAdditions 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 [#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. 
+{{{
+      {
+        int geni_api;
+        struct geni_api_versions {
+             URL <this API version #>;
+             [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 [#ReturnStruct larger set of codes with specific meanings required by this API, described below]. 
+
+|| '''''Error''''' || '''''Condition''''' ||
+|| `ERROR`         || Internal error ||
+|| `SERVERERROR`   || Server error ||
+|| `BUSY`          || Server busy; try again later ||
+
+==== 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 [#DocumentingAggregateAdditions 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 [#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 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 [wiki:DRAFT_GAPI_AM_API_V2#ListResources AM API overview page].
+
+=== Arguments ===
+
+ `credentials[]`::
+   [#CredentialsArgument An array of credentials with particular semantics].  
+
+ `options`::
+    An [http://www.xmlrpc.com/spec XML-RPC] struct containing members indicating the set of resources that the caller is interested in, or the format of the result. [#Options Semantics of this argument are described below].  Aggregates should [#DocumentingAggregateAdditions 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 [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_slice_urn`::
+    Optional. An [http://www.xmlrpc.com/spec 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 [wiki:GeniApiIdentifiers GENI wiki page].
+
+ `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. The [#RSpecs 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 [#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 the slice ||
+|| `BUSY`          || Slice is temporarily locked, try again later ||
+|| `BUSY`          || Server is temporarily busy, 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 [wiki:DRAFT_GAPI_AM_API_V2#CreateSliver 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 [wiki:GeniApiIdentifiers GENI wiki page].
+
+ `credentials`::
+   [#CredentialsArgument 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 [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:DRAFT_GAPI_AM_API_V2#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}}}).
+
+  `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`::
+    [#Options A struct with particular semantics described below]. Aggregates should [#DocumentingAggregateAdditions 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 [#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`::
+ The return value is an RSpec matching the [http://www.protogeni.net/trac/protogeni/wiki/RSpec GENI standard] manifest RSpec [http://www.geni.net/resources/rspec/3/manifest.xsd 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 are expected to preserve in the manifest 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 [#RSpecs 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 [#ReturnStruct 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 ||
+|| `BUSY`          || Server is temporarily busy, try again later ||
+|| `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 [wiki:DRAFT_GAPI_AM_API_V2#DeleteSliver 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 [wiki:GeniApiIdentifiers GENI wiki page].
+
+ `credentials`::
+   [#CredentialsArgument An array of credentials with particular semantics]. 
+
+  `options`::
+    [#Options A struct with particular semantics described below].  Aggregates should [#DocumentingAggregateAdditions 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 [#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`::
+     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 [#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 || 
+|| `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 ||
+|| `BUSY`          || Server is temporarily busy, 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 [wiki:DRAFT_GAPI_AM_API_V2#SliverStatus 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 [wiki:GeniApiIdentifiers GENI wiki page].
+
+ `credentials`::
+   [#CredentialsArgument An array of credentials with particular semantics].
+
+  `options`::
+    [#Options A struct with particular semantics described below]. Aggregates should [#DocumentingAggregateAdditions 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 [#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`::
+    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 [#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 || 
+|| `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 ||
+|| `BUSY`          || Server is temporarily busy, 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 [#DocumentingAggregateAdditions 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 [wiki:GeniApiIdentifiers 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 [wiki:DRAFT_GAPI_AM_API_V2#RenewSliver 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 [wiki:GeniApiIdentifiers GENI wiki page].
+
+ `credentials`::
+   [#CredentialsArgument An array of credentials with particular semantics]. 
+
+ `expiration_time`::
+    A string in [http://tools.ietf.org/html/rfc3339 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`::
+    [#Options A struct with particular semantics described below]. Aggregates should [#DocumentingAggregateAdditions 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 [#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`::
+     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 [#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 || 
+|| `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 ||
+|| `BUSY`          || Server is temporarily busy, 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 [wiki:DRAFT_GAPI_AM_API_V2#Shutdown 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 [wiki:GeniApiIdentifiers GENI wiki page].
+
+ `credentials`::
+   [#CredentialsArgument An array of credentials with particular semantics]. 
+
+  `options`::
+    [#Options A struct with particular semantics described below]. Aggregates should [#DocumentingAggregateAdditions 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 [#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`::
+     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 [#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 || 
+|| `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 [wiki:GEC10RSpec the GENI community agreed] that GENI RSpecs would be in what was the [http://www.protogeni.net/trac/protogeni/wiki/RSpec 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 [http://www.protogeni.net/trac/protogeni/wiki/RSpecExtensions2 wiki].
+
+For more information:
+ * [http://www.geni.net/resources/rspec/3 Official GENI v3 RSpec schemas]
+ * [http://www.protogeni.net/trac/protogeni/wiki/RSpec GENI standard (was ProtoGENI v2) format]
+ * [http://www.protogeni.net/trac/protogeni/wiki/RSpecExtensions2 RSpec extension information]
+ * [http://www.protogeni.net/trac/protogeni/wiki/RSpecSchema2 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 [wiki:GeniApiCredentials 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 [#DocumentingAggregateAdditions 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 [#DocumentingAggregateAdditions 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 [attachment:geni-error-codes.xml 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 [attachment:geni-am-types.xml 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 [attachment:geni-error-codes.xml 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, or server); 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. 
+
+-----
+== 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 [http://xmlrpc-c.sourceforge.net/introspection.html 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.