Changes between Version 13 and Version 14 of DRAFT_GAPI_AM_API_V2


Ignore:
Timestamp:
12/13/11 16:13:31 (10 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • DRAFT_GAPI_AM_API_V2

    v13 v14  
    1 [[PageOutline]]
    2 
    3 = GENI Aggregate Manager API Version 2 =
    4 
    5 The GENI Aggregate Manager API allows aggregates to advertise resources and to allocate resources to Slices in the form of Slivers.
    6 
    7 This is the GENI AM API Version '''2'''.
    8 
    9 See Also:
    10  * [wiki:DRAFT_GAPI_AM_API_V2_DETAILS API Version 2 Details page]
    11  * [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf Slice-based Facility Architecture (SFA) specification]
    12  * [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa-impl.pdf PlanetLab Implementation of the Slice-Based Facility Architecture]
    13  * [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2 ProtoGENI Component Manager API revision 2]
    14  * [wiki:GeniApi GENI API] implementation status
    15  * [wiki:GeniApiCredentials GENI credentials] for authorization
    16  * [wiki:GeniApiCertificates GENI certificates] for authentication. The GENI AM API uses XML-RPC over SSL with client authentication using certificates.
    17  * [wiki:DRAFT_GAPI_AM_API_DRAFT Draft API Revisions] proposed for future versions of this API
    18  * [wiki:DRAFT_GAPI_AM_API_ISSUES Open issues with this API]
    19 
    20 == Versions ==
    21 
    22  * Latest: 2 - Documented on this page. Changes since v1 include:
    23   * Includes Change Sets A and B from the [wiki:DRAFT_GAPI_AM_API_V2_DELTAS v2 Deltas page]
    24   * 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]
    25   * Include additional options in !GetVersion and !ListResources to allow aggregates to specify the RSpec formats they support
    26   * 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.
    27   * 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.
    28  * Previous: [wiki:DRAFT_GAPI_AM_API_V1 Version 1]
    29  * [wiki:DRAFT_GAPI_AM_API_DRAFT Draft change for version 3+
    30   * Covers changes proposed for future versions of this API. Documented changes include:
    31   * Change Set C: Add an !UpdateSliver method to add/remove/modify resources from a slice at an aggregate
    32   * Change Set D: Modify the API methods to explicitly support multiple slivers per slice at an aggregate
    33   * Change Set E: Add the use of Tickets to API methods
    34   * Others to be proposed
    35 
    36 -----
    37 == Changes since Version 1 ==
    38 
    39 Includes Change Sets A and B from the [wiki:DRAFT_GAPI_AM_API_V2_DELTAS v2 Deltas page].
    40 
    41 === Change Set A: RSpecs are XML documents following GENI schemas ===
    42 
    43 '''Note''': At the GEC12 coding sprint, this change set was modified slightly from that which is widely implemented. This change
    44  - Removed the {{{default_ad_rspec}}} value from !GetVersion
    45  - Made the {{{rspec_version}}} argument to !ListResources required and renamed it {{{geni_rspec_version}}}
    46  - Renamed the other return values from !GetVersion to use the {{{geni_}}} naming prefix
    47 
    48 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:
    49  * 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:DRAFT_GAPI_AM_API_V2_DETAILS#RSpecs Use of RSpecs in the AM API is well proscribed].
    50  * Include additional options in !GetVersion and !ListResources to allow aggregates to support the GENI RSpecs in addition to their own native format.
    51 
    52 === Change Set B: Flexible arguments and returns ===
    53 
    54 This change set was adopted at GEC12 for inclusion in AM API version 2.
    55 
    56  * 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:DRAFT_GAPI_AM_API_V2_DETAILS#options version 2 Details wiki page].
    57  * Method returns are modified to return at least 3 name/value pairs, with arbitrary additional such pairs.
    58   * {{{code}}} indicates success or error return. This itself is an XML-RPC struct, whose content is defined.
    59   * {{{value}}} is the return value as specified in AM API v1 or as modified by Change Set A (RSpec, etc), and
    60   * {{{output}}} is a human readable indication of the nature of the return or error.
    61   * Aggregates are free to use other additional name/value pairs in the return struct.
    62   * Commentary on the return structure is [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#ReturnStruct documented].
    63  * Aggregates are free to support additional options and return values, but must document them as [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#DocumentingAggregateAdditions discussed]
    64  * Aggregate may support multiple versions of the AM API, [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#SupportingMultipleAPIVersions as discussed]
    65 
    66 -----
    67 == API Overview ==
    68 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.
    69 
    70 === API Protocols and Data Structures ===
    71 
    72 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.
    73 
    74 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.
    75 
    76 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:DRAFT_GAPI_AM_API_V2_DETAILS#RSpecs the details page].
    77 
    78 === Using the GENI AM API ===
    79 
    80 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.
    81 
    82 !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.
    83 
    84 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.
    85 
    86 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.
    87 
    88 Client work flow:
    89  0. <Experimenter gets a [wiki:GeniApiCertificates GENI certificate] and slice [wiki:GeniApiCredentials credential]>
    90  1. {{{GetVersion()}}}: learn RSpec formats supported at this aggregate
    91  2. {{{ListResources(<user credential>, options)}}}: get Ad RSpec describing available resources
    92  3. <Experimenter constructs a request RSpec>
    93  4. {{{CreateSliver(<slice URN>, <slice credential>, <request RSpec>, <users struct>, {})}}}:
    94   * Aggregate reserves and starts resources
    95   * Return is a manifest RSpec describing the reserved resources
    96  6. {{{SliverStatus(<slice URN>, <slice credential>, <new time>, {})}}} to check that resources are starting
    97  7. {{{RenewSliver(<slice URN>, <slice credential>, {})}}} to extend reservation
    98  8. <Experimenter uses resources>
    99  9. {{{DeleteSliver(<slice URN>, <slice credential>, {})}}} when done
    100 
    101 -----
    102 == API Methods ==
    103 
    104 === !GetVersion ===
    105 Get static version and configuration information about this aggregate. Return includes:
    106  * The version of the GENI Aggregate Manager API supported by this aggregate manager instance
    107  * URLs for other versions of this API supported by this aggregate
    108  * The RSpec formats accepted at this aggregate
    109  * Other information about the configuration of this aggregate.
    110 
    111 For details on the arguments, return structure, and semantics, see [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#GetVersionDetails the details page].
    112 
    113 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.
    114 
    115 {{{
    116 struct GetVersion([optional: struct options])
    117 }}}
    118 
    119 The result is an [http://www.xmlrpc.com/spec XML-RPC] struct with at least the following members:
    120 
    121 {{{
    122 {
    123   int geni_api;
    124   struct code = {
    125        int geni_code;
    126        [optional: string am_type;]
    127        [optional: int am_code;]
    128          }
    129   struct value
    130       {
    131         int geni_api;
    132         struct geni_api_versions {
    133              URL <this API version #>; # value is a URL, name is a number
    134              [optional: other supported API versions and the URLs where they run]
    135         }
    136         array geni_request_rspec_versions of {
    137              string type;
    138              string version;
    139              string schema;
    140              string namespace;
    141              array extensions of string;
    142         };
    143         array geni_ad_rspec_versions of {
    144              string type;
    145              string version;
    146              string schema;
    147              string namespace;
    148              array extensions of string;
    149         };
    150       }
    151   string output;
    152 }
    153 }}}
    154 
    155 ==== Arguments Summary ====
    156  * {{{options}}}: Optional. [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#options An empty struct with particular semantics described on the Details page].  Aggregates should [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#DocumentingAggregateAdditions document new options arguments].
    157 
    158 ==== Return Summary ====
    159 
    160 As with all AM API methods, the return is an XML-RPC struct. For !GetVersion, it includes:
    161  * The standard AM API {{{code}}}, {{{value}}}, and {{{output}}} entries. For details, see [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#ReturnStruct the Details page]
    162  * {{{geni_api}}}: integer version of this API ('''2'''). Repeated here for backwards compatibility.
    163 
    164 !GetVersion {{{value}}} return members:
    165  * {{{geni_api}}} = '''2''' (Integer current version of this API).
    166  * List of versions of the API supported by this aggregate. For details on doing this, see [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#SupportingMultipleAPIVersions the Details page].
    167  * List of request RSpec formats supported by this aggregate. For details on RSpecs, see [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#RSpecs the Details page].
    168  * List of advertisement RSpec formats supported by this aggregate. For details on RSpecs, see [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#RSpecs the Details page].
    169 
    170 For details on !GetVersion arguments, returns, and semantics, and a sample minimal return, see [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#GetVersionDetails the Details page].
    171 
    172 ----
    173 === !ListResources ===
    174 
    175 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.
    176 
    177 {{{
    178 struct ListResources(string credentials[], struct options)
    179 }}}
    180 
    181 Note that the {{{options}}} argument includes one required option {{{geni_rspec_version}}}.
    182 
    183 As with all AM API methods, the return is an [http://www.xmlrpc.com/spec XML-RPC] struct with at least the following members:
    184 
    185 {{{
    186 {
    187   struct code = {
    188        int geni_code;
    189        [optional: string am_type;]
    190        [optional: int am_code;]
    191          }
    192   string value;
    193   string output;
    194 }
    195 }}}
    196 
    197 For details on the standard AM API return struct and {{{code}}}, {{{value}}}, and {{{output}}} entries, see [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#ReturnStruct the Details page].
    198 
    199 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).
    200 
    201 ==== Arguments Summary ====
    202  *  {{{credentials[]}}}: [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#credentialsArgument An array of credentials granting the caller privileges to perform this operation].
    203 
    204  * {{{options}}}: [wiki:DRAFT_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:DRAFT_GAPI_AM_API_V2_DETAILS#Arguments1 the Details page]. Aggregates should [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#DocumentingAggregateAdditions document new options arguments].
    205 
    206 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:DRAFT_GAPI_AM_API_V2_DETAILS#Arguments1 the meaning and semantics of each].
    207 
    208 {{{
    209 {
    210   boolean geni_available;
    211   boolean geni_compressed;
    212   string geni_slice_urn;
    213   struct geni_rspec_version {
    214     string type;
    215     string version;
    216   };
    217 }
    218 }}}
    219 
    220 ==== Return Summary ====
    221 
    222 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.
    223 
    224 The details page has details on !ListResources arguments, [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#Return1 returns], and semantics.
    225 ----
    226 === !CreateSliver ===
    227 
    228 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.
    229 
    230 {{{
    231 struct CreateSliver(string slice_urn,
    232                     string credentials[],
    233                     string rspec,
    234                     struct users[],
    235                     struct options)
    236 }}}
    237 
    238 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).
    239 
    240 
    241 ==== Arguments Summary ====
    242  * {{{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].
    243 
    244  *  {{{credentials[]}}}: [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#credentialsArgument An array of credentials granting the caller privileges to perform this operation].
    245 
    246  * {{{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}}}.
    247 
    248  * {{{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:DRAFT_GAPI_AM_API_V2_DETAILS the V2 details page].
    249 
    250  * {{{options}}}: [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#options An empty struct with particular semantics described on the Details page].  Aggregates should [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#DocumentingAggregateAdditions document new options arguments].
    251 
    252 ==== Return Summary ====
    253 !CreateSliver reserves the requested resources if possible. The aggregate then (asynchronously) starts those resources.
    254 As with all AM API methods, the return is an XML-RPC struct (see [wiki:DRAFT_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.
    255 
    256 For details on !CreateSliver arguments, returns, and semantics see the [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#CreateSliverDetails V2 details page].
    257 ----
    258 === !DeleteSliver ===
    259 
    260 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.
    261 
    262 {{{
    263 struct DeleteSliver(string slice_urn, string credentials[], struct options)
    264 }}}
    265 
    266 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).
    267 
    268 ==== Arguments Summary ====
    269  * {{{slice_urn}}}: The URN of the slice for which all resources will be freed.
    270 
    271  *  {{{credentials[]}}}: [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#credentialsArgument An array of credentials granting the caller privileges to perform this operation].
    272 
    273  * {{{options}}}: [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#options An empty struct with particular semantics described on the Details page].  Aggregates should [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#DocumentingAggregateAdditions document new options arguments].
    274 
    275 ==== Return Summary ====
    276 
    277 As with all AM API methods, the return is an XML-RPC struct (see [wiki:DRAFT_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.
    278 
    279 For details on !DeleteSliver arguments, returns, and semantics, see [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#DeleteSliverDetails the V2 details page].
    280 ----
    281 === !SliverStatus ===
    282 
    283 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.
    284 
    285 {{{
    286 struct SliverStatus(string slice_urn, string credentials[], struct options)
    287 }}}
    288 
    289 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.
    290 
    291 
    292 ==== Arguments Summary ====
    293  * {{{slice_urn}}}: The URN of the slice for which the resource status is desired.
    294 
    295  *  {{{credentials[]}}}: [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#credentialsArgument An array of credentials granting the caller privileges to perform this operation].
    296 
    297  * {{{options}}}: [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#options An empty struct with particular semantics described on the Details page].  Aggregates should [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#DocumentingAggregateAdditions document new options arguments].
    298 
    299 ==== Return Summary ====
    300 
    301 As with all AM API methods, the return is an XML-RPC struct (see [wiki:DRAFT_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.
    302 
    303 {{{
    304 {
    305   geni_urn: <sliver URN>
    306   geni_status: ready
    307   geni_resources: [ { geni_urn: <resource URN>
    308                       geni_status: ready
    309                       geni_error: ''},
    310                     { geni_urn: <resource URN>
    311                       geni_status: ready
    312                       geni_error: ''}
    313                   ]
    314 }
    315 }}}
    316 
    317 For details on !SliverStatus arguments, returns, and semantics, see [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#SliverStatusDetails the V2 details page].
    318 ----
    319 === !RenewSliver ===
    320 
    321 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.
    322 
    323 {{{
    324 struct RenewSliver(string slice_urn,
    325                     string credentials[],
    326                     string expiration_time,
    327                     struct options)
    328 }}}
    329 
    330 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.
    331 
    332 
    333 ==== Arguments Summary ====
    334  * {{{slice_urn}}}: The URN of the slice for which the resource reservation will be extended.
    335 
    336  *  {{{credentials[]}}}: [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#credentialsArgument An array of credentials granting the caller privileges to perform this operation].
    337 
    338  * {{{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.
    339 
    340  * {{{options}}}: [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#options An empty struct with particular semantics described on the Details page].  Aggregates should [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#DocumentingAggregateAdditions document new options arguments].
    341 
    342 ==== Return Summary ====
    343 
    344 As with all AM API methods, the return is an XML-RPC struct (see [wiki:DRAFT_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.
    345 
    346 For details on !RenewSliver arguments, returns, and semantics, see [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#RenewSliverDetails the V2 details wiki page].
    347 ----
    348 === Shutdown ===
    349 
    350 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.
    351 
    352 {{{
    353 struct Shutdown(string slice_urn, string credentials[], struct options)
    354 }}}
    355 
    356 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.
    357 
    358 
    359 ==== Arguments Summary ====
    360  * {{{slice_urn}}}: The URN of the slice for which all resources will be halted.
    361 
    362  *  {{{credentials[]}}}: [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#credentialsArgument An array of credentials granting the caller privileges to perform this operation].
    363 
    364  * {{{options}}}: [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#options An empty struct with particular semantics described on the Details page].  Aggregates should [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#DocumentingAggregateAdditions document new options arguments].
    365 
    366 ==== Return Summary ====
    367 
    368 As with all AM API methods, the return is an XML-RPC struct (see [wiki:DRAFT_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.
    369 
    370 For details on Shutdown arguments, returns, and semantics, see [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#ShutdownDetails the V2 details wiki].
     1See wiki:GAPI_AM_API_V2