Changes between Initial Version and Version 1 of GAPI_AM_API_V2

Timestamp:

12/12/11 10:56:59 (12 years ago)

Author:

Aaron Helsinger

Comment:

--

GAPI_AM_API_V2

@@ +1 @@
+[[PageOutline]]
+
+= GENI Aggregate Manager API Version 2 =
+
+The GENI Aggregate Manager API allows aggregates to advertise resources and to allocate resources to Slices in the form of Slivers. 
+
+This is the GENI AM API Version '''2'''.
+
+See Also:
+ * [wiki:GAPI_AM_API_V2_DETAILS API Version 2 Details page]
+ * [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf Slice-based Facility Architecture (SFA) specification]
+ * [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa-impl.pdf PlanetLab Implementation of the Slice-Based Facility Architecture]
+ * [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2 ProtoGENI Component Manager API revision 2]
+ * [wiki:GeniApi GENI API] implementation status
+ * [wiki:GeniApiCredentials GENI credentials] for authorization
+ * [wiki:GeniApiCertificates GENI certificates] for authentication. The GENI AM API uses XML-RPC over SSL with client authentication using certificates.
+ * [wiki:GAPI_AM_API_DRAFT Draft API Revisions] proposed for future versions of this API
+ * [wiki:GAPI_AM_API_ISSUES Open issues with this API]
+
+== Versions ==
+
+ * Latest: 2 - Documented on this page. Changes since v1 include:
+  * Includes Change Sets A and B from the [wiki:GAPI_AM_API_V2_DELTAS v2 Deltas page]
+  * Specify that GENI RSpecs are XML documents following standard schemas published [http://www.geni.net/resources/rspec on geni.net] and documented [http://www.protogeni.net/trac/protogeni/wiki/RSpec on the ProtoGENI wiki]
+  * Include additional options in !GetVersion and !ListResources to allow aggregates to specify the RSpec formats they support
+  * Add an 'options' argument, an XML-RPC struct, to all methods with no required values. This allows Aggregates to innovate or support resource-specific functionality.
+  * Modify all methods to return an XML-RPC struct consisting of at least (1) a return 'code', (2) the 'value' specified by v1 of the API, and (3) a human-readable 'output' on errors. Aggregates are free to innovate by adding additional return values.
+ * Previous: [wiki:GAPI_AM_API_V1 Version 1] 
+ * [wiki:GAPI_AM_API_DRAFT Draft change for version 3+
+  * Covers changes proposed for future versions of this API. Documented changes include:
+  * Change Set C: Add an !UpdateSliver method to add/remove/modify resources from a slice at an aggregate
+  * Change Set D: Modify the API methods to explicitly support multiple slivers per slice at an aggregate
+  * Change Set E: Add the use of Tickets to API methods
+  * Others to be proposed
+
+-----
+== Changes since Version 1 ==
+
+Includes Change Sets A and B from the [wiki:GAPI_AM_API_V2_DELTAS v2 Deltas page].
+
+=== Change Set A: RSpecs are XML documents following GENI schemas ===
+
+'''Note''': At the GEC12 coding sprint, this change set was modified slightly from that which is widely implemented. This change
+ - Removed the {{{default_ad_rspec}}} value from !GetVersion
+ - Made the {{{rspec_version}}} argument to !ListResources required and renamed it {{{geni_rspec_version}}}
+ - Renamed the other return values from !GetVersion to use the {{{geni_}}} naming prefix
+
+Other parts of this change set have been discussed and most current aggregates already implement them. The community has agreed to include this change in version 2 of this API. This change will:
+ * Specify that GENI RSpecs comply with GENI standard XML schemas as posted at http://www.geni.net/resources/rspec. GENI RSpec v3 is what was the ProtoGENI v2 schemas as documented [http://www.protogeni.net/trac/protogeni/wiki/RSpec on the ProtoGENI wiki]. [wiki:GAPI_AM_API_V2_DETAILS#RSpecs Use of RSpecs in the AM API is well proscribed].
+ * Include additional options in !GetVersion and !ListResources to allow aggregates to support the GENI RSpecs in addition to their own native format. 
+
+=== Change Set B: Flexible arguments and returns ===
+
+This change set was adopted at GEC12 for inclusion in AM API version 2.
+
+ * All methods take an ''options'' argument, which is a non null XML-RPC struct. No required options are added with this change - the struct may be empty (except at !ListResources). Details are on the [wiki:GAPI_AM_API_V2_DETAILS#options version 2 Details wiki page].
+ * Method returns are modified to return at least 3 name/value pairs, with arbitrary additional such pairs. 
+  * {{{code}}} indicates success or error return. This itself is an XML-RPC struct, whose content is defined. 
+  * {{{value}}} is the return value as specified in AM API v1 or as modified by Change Set A (RSpec, etc), and 
+  * {{{output}}} is a human readable indication of the nature of the return or error. 
+  * Aggregates are free to use other additional name/value pairs in the return struct.
+  * Commentary on the return structure is [wiki:GAPI_AM_API_V2_DETAILS#ReturnStruct documented].
+ * Aggregates are free to support additional options and return values, but must document them as [wiki:GAPI_AM_API_V2_DETAILS#DocumentingAggregateAdditions discussed]
+ * Aggregate may support multiple versions of the AM API, [wiki:GAPI_AM_API_V2_DETAILS#SupportingMultipleAPIVersions as discussed]
+
+-----
+== API Overview ==
+The GENI Aggregate Manager API is the control plane interface by which experimenters discover, reserve and control resources at resource providers. It does not include resource specific interactions, application level interactions, or monitoring and management functions.
+
+=== API Protocols and Data Structures ===
+
+GENI specifies that the AM API is provided via [http://www.xmlrpc.com/spec XML-RPC] over an SSL connection. Aggregate Managers shall require client side [wiki:GeniApiCertificates GENI certificates] to authenticate users, accepting only certificates that comply with the adopted [wiki:GeniApiCertificates GENI certificates] standards. The GENI AM API therefore assumes that users have already been authenticated, and that the aggregate manager has available the client certificate to identify the user.
+
+Clients are authorized to take actions at aggregates using [wiki:GeniApiCredentials GENI credentials]. To that end, all methods that require authorization take an argument {{{credentials}}}. In particular, operations on a single GENI slice will require a credential that authorizes the client whose certificate was used to authenticate to operate on the slice named by a {{{slice_urn}}} argument to the method.
+
+The primary data structure used within this API is a resource specification, known as an RSpec. These XML documents follow a specific set of schemas. They are used by aggregates to list and describe local resources (advertisement RSpecs), by experimenters to describe desired resources (request RSpecs), and then by aggregates to describe reserved resources (manifest RSpecs). For more information on RSpecs, see [wiki:GAPI_AM_API_V2_DETAILS#RSpecs the details page].
+
+=== Using the GENI AM API ===
+
+Clients (experimenters) use the AM API to discover resources (!ListResources), request resources (!CreateSliver), check the status of resources as they are started (!SliverStatus), extend their reservation (!RenewSliver), and then return the resources when done (!DeleteSliver). Client tools may use !GetVersion to ensure aggregates speak a compatible version of the AM API and known formats for RSpecs. Administrators may call Shutdown to stop the resources of a slice at this aggregate, perhaps if that slice is misbehaving.
+
+!ListResources returns to the client an advertisement RSpec - a detailed listing of the resources available at that aggregate. From this information, the experimenter may determine which resources to reserve for their use. The RSpec should also have enough information to help the experimenter set the initial configuration for their resources.
+
+Once the experimenter has selected the resources they want and how to configure them, they produce a request RSpec, detailing the resources they want and how they should be configured. They separately contact their slice authority to obtain a slice credential, granting them rights to reserve resources for that slice. The experimenter then calls !CreateSliver on this API, passing in both the slice credential and the request RSpec. The aggregate then attempts to satisfy the experimenter's resource request. If the aggregate can satisfy the request, the aggregate reserves the resources for the experimenter. The aggregate then starts the process of instantiating the resources and configuring them as requested in the request RSpec. Once that process has started, the !CreateSliver call returns with a manifest RSpec, listing the resources as reserved and initially configured for the experimenter.
+
+The experimenter can then poll the aggregate manager to watch as the resources are configured and become ready for use, by calling !SliverStatus. Once the resources are ready for use, the experimenter will start using the resources. The experimenter will also call !RenewSliver to request that their reservation lasts as long as they require the resources for. When the experimenter is done using the resources, they call !DeleteSliver to end their reservation. The aggregate then stops and clears the resources, freeing them for use by other clients.
+
+Client work flow: 
+ 0. <Experimenter gets a [wiki:GeniApiCertificates GENI certificate] and slice [wiki:GeniApiCredentials credential]>
+ 1. {{{GetVersion()}}}: learn RSpec formats supported at this aggregate
+ 2. {{{ListResources(<user credential>, options)}}}: get Ad RSpec describing available resources
+ 3. <Experimenter constructs a request RSpec>
+ 4. {{{CreateSliver(<slice URN>, <slice credential>, <request RSpec>, <users struct>, {})}}}: 
+  * Aggregate reserves and starts resources
+  * Return is a manifest RSpec describing the reserved resources
+ 6. {{{SliverStatus(<slice URN>, <slice credential>, <new time>, {})}}} to check that resources are starting
+ 7. {{{RenewSliver(<slice URN>, <slice credential>, {})}}} to extend reservation
+ 8. <Experimenter uses resources>
+ 9. {{{DeleteSliver(<slice URN>, <slice credential>, {})}}} when done
+
+-----
+== API Methods ==
+
+=== !GetVersion ===
+Get static version and configuration information about this aggregate. Return includes:
+ * The version of the GENI Aggregate Manager API supported by this aggregate manager instance
+ * URLs for other versions of this API supported by this aggregate
+ * The RSpec formats accepted at this aggregate
+ * Other information about the configuration of this aggregate. 
+
+For details on the arguments, return structure, and semantics, see [wiki:GAPI_AM_API_V2_DETAILS#GetVersionDetails the details page].
+
+The !GetVersion operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#GetVersion GetVersion] operation. The [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA] specification does not include this operation.
+
+{{{
+struct GetVersion([optional: struct options])
+}}}
+
+The result is an [http://www.xmlrpc.com/spec XML-RPC] struct with at least the following members:
+
+{{{
+{
+  int geni_api;
+  struct code = {
+       int geni_code;
+       [optional: string am_type;]
+       [optional: int am_code;]
+         }
+  struct value
+      {
+        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;
+        };
+      }
+  string output;
+}
+}}}
+
+==== Arguments Summary ====
+ * {{{options}}}: Optional. [wiki:GAPI_AM_API_V2_DETAILS#options An empty struct with particular semantics described on the Details page].  Aggregates should [wiki:GAPI_AM_API_V2_DETAILS#DocumentingAggregateAdditions document new options arguments].
+
+==== Return Summary ====
+
+As with all AM API methods, the return is an XML-RPC struct. For !GetVersion, it includes:
+ * The standard AM API {{{code}}}, {{{value}}}, and {{{output}}} entries. For details, see [wiki:GAPI_AM_API_V2_DETAILS#ReturnStruct the Details page]
+ * {{{geni_api}}}: integer version of this API ('''2'''). Repeated here for backwards compatibility.
+
+!GetVersion {{{value}}} return members:
+ * {{{geni_api}}} = '''2''' (Integer current version of this API).
+ * List of versions of the API supported by this aggregate. For details on doing this, see [wiki:GAPI_AM_API_V2_DETAILS#SupportingMultipleAPIVersions the Details page]. 
+ * List of request RSpec formats supported by this aggregate. For details on RSpecs, see [wiki:GAPI_AM_API_V2_DETAILS#RSpecs the Details page]. 
+ * List of advertisement RSpec formats supported by this aggregate. For details on RSpecs, see [wiki:GAPI_AM_API_V2_DETAILS#RSpecs the Details page]. 
+
+For details on !GetVersion arguments, returns, and semantics, and a sample minimal return, see [wiki:GAPI_AM_API_V2_DETAILS#GetVersionDetails the Details page].
+
+----
+=== !ListResources ===
+
+Return a listing and description of available resources at this aggregate, or resources allocated to a named slice at this aggregate. The resource listing and description provides sufficient information for clients to select among available resources, or to use reserved resources. These listings are known as RSpecs.
+
+{{{
+struct ListResources(string credentials[], struct options)
+}}}
+
+Note that the {{{options}}} argument includes one required option {{{geni_rspec_version}}}.
+
+As with all AM API methods, the return is an [http://www.xmlrpc.com/spec XML-RPC] struct with at least the following members:
+
+{{{
+{
+  struct code = {
+       int geni_code;
+       [optional: string am_type;]
+       [optional: int am_code;]
+         }
+  string value;
+  string output;
+}
+}}}
+
+For details on the standard AM API return struct and {{{code}}}, {{{value}}}, and {{{output}}} entries, see [wiki:GAPI_AM_API_V2_DETAILS#ReturnStruct the Details page].
+
+This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#DiscoverResources DiscoverResources] operation and to the [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA]'s !GetResources operation (sec. 6.2.4).
+
+==== Arguments Summary ====
+ *  {{{credentials[]}}}: [wiki:GAPI_AM_API_V2_DETAILS#credentialsArgument An array of credentials granting the caller privileges to perform this operation].
+
+ * {{{options}}}: [wiki:GAPI_AM_API_V2_DETAILS#options A non-empty struct with particular semantics described on the Details page].  For this method, options indicate the set of resources that the caller is interested in, or the format of the result. Note that this struct includes one required argument {{{geni_rspec_version}}}. For semantics see [wiki:GAPI_AM_API_V2_DETAILS#Arguments1 the Details page]. Aggregates should [wiki:GAPI_AM_API_V2_DETAILS#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. See the details page for an explanation of [wiki:GAPI_AM_API_V2_DETAILS#Arguments1 the meaning and semantics of each].
+
+{{{
+{
+  boolean geni_available;
+  boolean geni_compressed;
+  string geni_slice_urn;
+  struct geni_rspec_version {
+    string type;
+    string version;
+  };
+}
+}}}
+
+==== Return Summary ====
+
+For !ListResources, {{{value}}} is an RSpec listing and describing resources at this aggregate. Depending on the arguments, this may be an advertisement RSpec showing all local resources, or one showing only available local resources, or a manifest RSpec of resources reserved for a particular slice. 
+
+The details page has details on !ListResources arguments, [wiki:GAPI_AM_API_V2_DETAILS#Return1 returns], and semantics.
+----
+=== !CreateSliver ===
+
+Allocate resources as described in a request RSpec argument to a slice with the named URN. This operation is expected to start the allocated resources asynchronously after the operation has successfully completed. Callers can check on the status of the resources using [#SliverStatus SliverStatus]. Resources will be reserved until a particular time, set by the aggregate according to policy. That expiration time will be no later than the expiration time of the provided slice credential. This method returns a listing and description of the resources reserved for the slice by this operation, in the form of a manifest RSpec.
+
+{{{
+struct CreateSliver(string slice_urn,
+                    string credentials[],
+                    string rspec,
+                    struct users[],
+                    struct options)
+}}}
+
+This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#CreateSliver CreateSliver] operation and to the [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA]'s !CreateSlice operation (sec. 6.2.1).
+
+
+==== Arguments Summary ====
+ * {{{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[]}}}: [wiki:GAPI_AM_API_V2_DETAILS#credentialsArgument An array of credentials granting the caller privileges 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}}}. 
+
+ * {{{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. This struct has particular required members, documented on [wiki:GAPI_AM_API_V2_DETAILS the V2 details page].
+
+ * {{{options}}}: [wiki:GAPI_AM_API_V2_DETAILS#options An empty struct with particular semantics described on the Details page].  Aggregates should [wiki:GAPI_AM_API_V2_DETAILS#DocumentingAggregateAdditions document new options arguments].
+
+==== Return Summary ====
+!CreateSliver reserves the requested resources if possible. The aggregate then (asynchronously) starts those resources. 
+As with all AM API methods, the return is an XML-RPC struct (see [wiki:GAPI_AM_API_V2_DETAILS#ReturnStruct the Details page]). The !CreateSliver method returns in the {{{value}}} entry a manifest 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. 
+
+For details on !CreateSliver arguments, returns, and semantics see the [wiki:GAPI_AM_API_V2_DETAILS#CreateSliverDetails V2 details page].
+----
+=== !DeleteSliver ===
+
+Delete any slivers at the given aggregate belonging to the given slice, by stopping the resources if they are still running, and then deallocating the resources associated with the slice.  When complete, this slice will own no resources on this aggregate - any such resources will have been stopped.
+
+{{{
+struct DeleteSliver(string slice_urn, string credentials[], struct options)
+}}}
+
+This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#DeleteSliver DeleteSliver] operation and to the [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA]'s !DeleteSlice operation (sec. 6.2.3).
+
+==== Arguments Summary ====
+ * {{{slice_urn}}}: The URN of the slice for which all resources will be freed.
+
+ *  {{{credentials[]}}}: [wiki:GAPI_AM_API_V2_DETAILS#credentialsArgument An array of credentials granting the caller privileges to perform this operation].
+
+ * {{{options}}}: [wiki:GAPI_AM_API_V2_DETAILS#options An empty struct with particular semantics described on the Details page].  Aggregates should [wiki:GAPI_AM_API_V2_DETAILS#DocumentingAggregateAdditions document new options arguments].
+
+==== Return Summary ====
+
+As with all AM API methods, the return is an XML-RPC struct (see [wiki:GAPI_AM_API_V2_DETAILS#ReturnStruct the Details page]). !DeleteSliver stops all the slice's resources and removes the reservation. It returns in the {{{value}}} slot {{{true}}} or {{{false}}} indicating whether it did this successfully. 
+
+For details on !DeleteSliver arguments, returns, and semantics, see [wiki:GAPI_AM_API_V2_DETAILS#DeleteSliverDetails the V2 details page].
+----
+=== !SliverStatus ===
+
+Get the status of a sliver or slivers belonging to the given slice at the given aggregate. Status may include other dynamic reservation or instantiation information as required by the resource type and aggregate. This method is used to provide updates on the state of the resources after the completion of !CreateSliver, which began to asynchronously provision and start the resources.
+
+{{{
+struct SliverStatus(string slice_urn, string credentials[], struct options)
+}}}
+
+This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#SliverStatus,WaitForStatus SliverStatus] operation. The [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA] specification does not include this operation.
+
+
+==== Arguments Summary ====
+ * {{{slice_urn}}}: The URN of the slice for which the resource status is desired.
+
+ *  {{{credentials[]}}}: [wiki:GAPI_AM_API_V2_DETAILS#credentialsArgument An array of credentials granting the caller privileges to perform this operation].
+
+ * {{{options}}}: [wiki:GAPI_AM_API_V2_DETAILS#options An empty struct with particular semantics described on the Details page].  Aggregates should [wiki:GAPI_AM_API_V2_DETAILS#DocumentingAggregateAdditions document new options arguments].
+
+==== Return Summary ====
+
+As with all AM API methods, the return is an XML-RPC struct (see [wiki:GAPI_AM_API_V2_DETAILS#ReturnStruct the Details page]). !SliverStatus returns the status of the overall reservation, and of each addressable resource within the reservation in an XML-RPC struct in the {{{value}}} entry.
+
+{{{
+{
+  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: ''}
+                  ]
+}
+}}}
+
+For details on !SliverStatus arguments, returns, and semantics, see [wiki:GAPI_AM_API_V2_DETAILS#SliverStatusDetails the V2 details page].
+----
+=== !RenewSliver ===
+
+Renews the resources in all slivers at this aggregate belonging to the given slice until the given time, extending the lifetime of the slice. Aggregates may limit how long reservations may be extended. Initial sliver expiration is set by aggregate policy, no later than the slice credential expiration time. 
+
+{{{
+struct RenewSliver(string slice_urn,
+                    string credentials[],
+                    string expiration_time, 
+                    struct options)
+}}}
+
+This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#RenewSlice RenewSlice] operation. The [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA] specification does not include this operation.
+
+
+==== Arguments Summary ====
+ * {{{slice_urn}}}: The URN of the slice for which the resource reservation will be extended.
+
+ *  {{{credentials[]}}}: [wiki:GAPI_AM_API_V2_DETAILS#credentialsArgument An array of credentials granting the caller privileges to perform this operation].
+
+ * {{{expiration_time}}}: The date-time string in [http://tools.ietf.org/html/rfc3339 RFC 3339] format in UTC when the reservation should be extended until.
+
+ * {{{options}}}: [wiki:GAPI_AM_API_V2_DETAILS#options An empty struct with particular semantics described on the Details page].  Aggregates should [wiki:GAPI_AM_API_V2_DETAILS#DocumentingAggregateAdditions document new options arguments].
+
+==== Return Summary ====
+
+As with all AM API methods, the return is an XML-RPC struct (see [wiki:GAPI_AM_API_V2_DETAILS#ReturnStruct the Details page]). The actual return in {{{value}}} is {{{true}}} or {{{false}}} indicating whether the reservation was successfully extended to the requested date and time.
+
+For details on !RenewSliver arguments, returns, and semantics, see [wiki:GAPI_AM_API_V2_DETAILS#RenewSliverDetails the V2 details wiki page].
+----
+=== Shutdown ===
+
+Perform an emergency shut down of a sliver or slivers at this aggregate belonging to the given slice. This operation is intended for administrative use. The sliver is shut down but remains available for further forensics. 
+
+{{{
+struct Shutdown(string slice_urn, string credentials[], struct options)
+}}}
+
+This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#Shutdown Shutdown] operation. The [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA] specification does not include this operation.
+
+
+==== Arguments Summary ====
+ * {{{slice_urn}}}: The URN of the slice for which all resources will be halted.
+
+ *  {{{credentials[]}}}: [wiki:GAPI_AM_API_V2_DETAILS#credentialsArgument An array of credentials granting the caller privileges to perform this operation].
+
+ * {{{options}}}: [wiki:GAPI_AM_API_V2_DETAILS#options An empty struct with particular semantics described on the Details page].  Aggregates should [wiki:GAPI_AM_API_V2_DETAILS#DocumentingAggregateAdditions document new options arguments].
+
+==== Return Summary ====
+
+As with all AM API methods, the return is an XML-RPC struct (see [wiki:GAPI_AM_API_V2_DETAILS#ReturnStruct the Details page]). The {{{value}}} return is a boolean indicating whether the resources associated with this reservation were successfully shut down to a state suitable for forensics.
+
+For details on Shutdown arguments, returns, and semantics, see [wiki:GAPI_AM_API_V2_DETAILS#ShutdownDetails the V2 details wiki].