Changes between Initial Version and Version 1 of GAPI_AM_API_V2_DELTAS


Ignore:
Timestamp:
12/12/11 11:01:34 (12 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • GAPI_AM_API_V2_DELTAS

    v1 v1  
     1
     2[[PageOutline]]
     3
     4= GENI AM API Changes from version 1 to version 2 =
     5
     6This page documents changes to the GENI Aggregate Manager API from [wiki:GAPI_AM_API_V1 version 1] to [wiki:GAPI_AM_API_V2 version 2]. It consists of the text describing the changes to the API which was used to define and adopt the changes to the API for version 2.
     7 * [wiki:GAPI_AM_API_V1 Version 1 of the GENI Aggregate Manager API]
     8 * [wiki:GAPI_AM_API_V2 Version 2 of the GENI Aggregate Manager API]
     9 * [wiki:GAPI_AM_API_DRAFT Draft changes to the GENI Aggregate Manager API] for future versions. That is where this text originally was written.
     10
     11== Summary of Changes ==
     12=== Change Set A: RSpecs are XML documents following GENI schemas ===
     13
     14'''Note''': At the GEC12 coding sprint, this change set was modified slightly from that which is widely implemented. This change
     15 - removed the {{{default_ad_rspec}}} value from !GetVersion
     16 - made the {{{rspec_version}}} argument to !ListResources required and renamed it {{{geni_rspec_version}}}
     17 - renamed the other return values from !GetVersion to use the {{{geni_}}} naming prefix
     18
     19Other 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.
     20
     21 * 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. RSpec and the ProtoGENI schemas are documented on [http://www.protogeni.net/trac/protogeni/wiki/RSpec the ProtoGENI wiki].
     22 * Include additional options in !GetVersion and !ListResources to allow aggregates to support the GENI RSpecs in addition to their own native format.
     23
     24=== Change Set B: Flexible arguments and returns ===
     25
     26 * All methods take an ''options'' argument, which is a non null XML struct. No required options are added with this change - the struct may be empty.
     27 * Method returns are modified to return at least 3 name/value pairs, with arbitrary additional such pairs.
     28  * {{{code}}} indicates success or error return. This itself is an XML-RPC struct, whose content is described below.
     29  * {{{value}}} is the return value as specified in AM API v1 or as modified by Change Set A (RSpec, etc), and
     30  * {{{output}}} is a human readable indication of the nature of the return or error.
     31  * Aggregates are free to use other additional name/value pairs in the return struct.
     32
     33== Adopted Change Details ==
     34
     35=== Change Set A ===
     36
     37'''Note''': At the GEC12 coding sprint, this change set was modified slightly from that which is widely implemented. This change
     38 - removed the {{{default_ad_rspec}}} value from !GetVersion
     39 - made the {{{rspec_version}}} argument to !ListResources required and renamed it {{{geni_rspec_version}}}
     40 - renamed the other return values from !GetVersion to use the {{{geni_}}} naming prefix
     41
     42''Note: The change to GENI standard RSpec schemas originally referenced ProtoGENI v2 RSpec schemas, hosted at www.protogeni.net. These schemas have now been re-branded as GENI v3 RSpec schemas and are hosted at http://www.geni.net/resources/rspec/3.'''
     43
     44''Note: Options in the geni_ namespace remain reserved, but not all GENI standard options need to be named with the geni_ prefix.''
     45
     46==== Part 1: Standardized XML-based GENI RSpecs ====
     47At 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].
     48
     49For more information:
     50 * [http://www.geni.net/resources/rspec/3 Official GENI v3 RSpec schemas]
     51 * [http://www.protogeni.net/trac/protogeni/wiki/RSpec GENI standard (was ProtoGENI v2) format]
     52 * [http://www.protogeni.net/trac/protogeni/wiki/RSpecExtensions2 RSpec extension information]
     53 * [http://www.protogeni.net/trac/protogeni/wiki/RSpecSchema2 RSpec schemas listing]
     54
     55Specific changes include:
     56 * !ListResources: Return value of !ListResources remains an [http://www.xmlrpc.com/spec XML-RPC] string, but its format and meaning are now proscribed.
     57
     58 The return value is an RSpec matching the [http://www.protogeni.net/trac/protogeni/wiki/RSpec GENI standard] RSpec in text format if {{{geni_compressed}}} is unspecified or set to {{{false}}}. The return value will be a ZLib compressed and then base 64 encoded string representation of the RSpec if {{{geni_compressed}}} is specified and set to {{{true}}}.
     59
     60This RSpec will be a [http://www.geni.net/resources/rspec/3/ad.xsd advertisement RSpec] when invoked with no {{{geni_slice_urn}}} option, representing the resources available at this aggregate. When the client supplies the {{{geni_slice_urn}}} option, then the aggregate will return a [http://www.geni.net/resources/rspec/3/manifest.xsd manifest RSpec], representing all resources allocated to that slice by this aggregate.
     61
     62 * !CreateSliver: rspec argument remains an [http://www.xmlrpc.com/spec XML-RPC] string, but its format and meaning are now proscribed.
     63
     64  `rspec`::
     65    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:GAPI_AM_API#ListResources ListResources].
     66
     67 * !CreateSliver: return value remains an [http://www.xmlrpc.com/spec XML-RPC] string, but its format and meaning are now proscribed.
     68
     69 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] indicating the resources that were allocated to the slice. The result RSpec may contain additional information about the allocated resources.
     70
     71==== Part 2: New RSpec Version Options ====
     72In order to allow aggregates to support both a native RSpec format (e.g. the standard !PlanetLab / SFA RSpecs) as well as the GENI-standard format (GENI v3, was ProtoGENI v2), we need new options to allow a client to request RSpecs in a particular format.
     73
     74Specifically, aggregates will advertise (in !GetVersion) the list of Advertisement and Request RSpec types they are willing to accept. And they will produce manifest RSpecs in a format matching the format of the !CreateSliver input request RSpec (e.g. return a GENI v3 manifest RSpec when given a GENI v3 request RSpec, and a native !PlanetLab manifest RSpec when given a !PlanetLab request RSpec).
     75
     76===== Contract details =====
     77
     78Aggregates 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.
     79
     80If 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 an {{{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}}}).
     81
     82If 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}}}.
     83
     84===== New !GetVersion required attributes =====
     85
     86Return the version of the GENI Aggregate Manager API and RSpecs supported by this aggregate.
     87
     88{{{
     89struct GetVersion()
     90}}}
     91
     92The result is an [http://www.xmlrpc.com/spec XML-RPC] struct with at least the following members:
     93
     94{{{
     95{
     96  int geni_api;
     97  array geni_request_rspec_versions of {
     98    string type;
     99    string version;
     100    string schema;
     101    string namespace;
     102    array extensions of string;
     103  };
     104  array geni_ad_rspec_versions of {
     105    string type;
     106    string version;
     107    string schema;
     108    string namespace;
     109    array extensions of string;
     110  };
     111}
     112}}}
     113
     114 `geni_api`::
     115    An integer indicating the revision of the Aggregate Manager API that an aggregate supports. This document describes API version 2 (two).
     116
     117 `geni_request_rspec_versions`::
     118   An array of data structures indicating the RSpec types accepted by this AM in a request.
     119
     120 `geni_ad_rspec_versions`::
     121   An array of data structures indicating what types of RSpec advertisements may be produced by this AM in !ListResources.
     122
     123Elements used within {{{geni_request_rspec_versions}}} and {{{geni_ad_rspec_versions}}}:
     124 `type`, `version`::
     125   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" and `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 www.geni.net.
     126
     127 `schema`::
     128   An optional URL pointing to a schema which can be used to verify the given type of RSpec.
     129
     130 `namespace`::
     131   An optional XML namespace which the RSpec of the given type belongs to.
     132
     133 `extensions`::
     134   An array of aggregate-specific strings denoting which extensions are supported. In the case of ProtoGENI, these are XML namespaces which denote the extension as a whole.
     135
     136Implementations can add additional members to the struct as desired. Implementations should choose an appropriate prefix to avoid conflicts, but avoid {{{geni_}}} which should be reserved for common options.
     137
     138This 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 other than through this method.
     139
     140===== New !ListResources Option =====
     141!ListResources will take an additional ''required'' option, {{{geni_rspec_version}}}, allowing a user to request an Advertisement or Manifest Rspec in a particular format. This struct must contain a {{{type}}} and {{{version}}} matching one of this Aggregate's advertised {{{geni_ad_rspec_versions}}}.
     142
     143Specifics:
     144
     145Return information about available resources or resources allocated to a slice.
     146
     147{{{
     148string ListResources(string credentials[], struct options)
     149}}}
     150
     151....
     152
     153 `options`::
     154    An [http://www.xmlrpc.com/spec XML-RPC] struct containing members indicating the set of resources the caller is interested in or the format of the result. In addition to the members specified below, callers can pass additional members that specific aggregate manager implementations might honor. Implementations should choose an appropriate prefix to avoid conflicts, but avoid {{{geni_}}} which should be reserved for common options.
     155
     156The following members are available for use in the options parameter. All aggregate managers are required to implement these options.
     157
     158{{{
     159{
     160  boolean geni_available;
     161  boolean geni_compressed;
     162  string geni_slice_urn;
     163  struct geni_rspec_version {
     164    string type;
     165    string version;
     166  };
     167}
     168}}}
     169
     170....
     171
     172 `geni_rspec_version`::
     173    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 {{{1}}} ('Bad Arguments') if it is missing.
     174
     175    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.
     176
     177    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 13 (UNSUPPORTED).
     178
     179===== New !CreateSliver behavior =====
     180If 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).
     181
     182=== Change Set B ===
     183
     184==== Part 1: Additional options argument ====
     185Adding support for additional functionality in the AM API is currently difficult. Many possible areas of innovation are variations on existing functions. This change adds flexibility in arguments to support such innovation.
     186
     187Under this proposal, each method will take an argument which is a set of name-value pairs (an XML-RPC struct, aka a property list). This argument is required for all methods except !GetVersion (where it is optional), but may be empty (non NULL but containing no name/value pairs). Aggregates may support new entries in this 'options' argument to allow new non-standardized functionality.
     188
     189Specifically, this change adds a final {{{struct options}}} argument to each of !GetVersion, !CreateSliver, !SliverStatus, !RenewSliver, !DeleteSliver,  and Shutdown. !ListResources already has that argument. The argument is optional for !GetVersion, but required for all other functions.
     190
     191Aggregates are compliant with this API change by accepting this argument; only for !ListResources are they required to handle any specific options. Similarly, clients are required to supply this argument to talk to compatible aggregates, but are only required to supply any particular options for !ListResources.
     192
     193In !GetVersion, this argument remains optional. Clients that only talk AM API v1 will get an error invoking most functions, when they leave off the {{{options}}} argument. Experimenters can then call !GetVersion (without the {{{options}}} argument). AM API v2 compliant Aggregates shall include the {{{geni_api}}} argument as a top-level entry in the return struct, specifying {{{2}}} to indicate to clients that this AM speaks version 2 of the AM API.  This allows experimenters to understand that they need to upgrade their client, or might instruct a clever client tool to automatically switch to version 2 syntax.
     194
     195Aggregates should not ''require'' any new options to any method - they should always have a reasonable default for any such option. Clients must always be able to work with any aggregate by simply supplying the options required by this API.
     196
     197Aggregates are encouraged to document any new options which they accept in any method, to bootstrap coordination with clients, and provide documentation for human experimenters. This API does not specify how aggregates provide that documentation. 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 options. Alternatively or additionally, aggregates may document options as part of their return from !GetVersion. This allows clients to either avoid communicating with an aggregate for which the client does not understand how to provide those options, or to tailor the client's request to provide those extra options.
     198
     199==== Part 2: Richer return values ====
     200In AM API v1, method failures come back sometimes as XML-RPC Faults, sometimes as ''False'', and is occasionally inconsistent across aggregates. Failures typically do not indicate how the Experimenter should modify their request for it to succeed, or if this is a server error. This proposed change expands and formalizes the return structures, to support semantically richer returns, allowing Experimenters better insight into both successes and failures, and how to respond.
     201
     202Allowing aggregates to return more information, on both errors and success, will allow for a richer client-server communication. It would also allow aggregates to give clients hints on how to use successful returns, or otherwise innovate within the bounds of the AM API.
     203
     204This change will modify all methods to return an XML-RPC struct (aka property list) on any application layer success, failure, and even on an error or for most exceptions. 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. This struct will contain the return value from the previous revision of the AM API as an entry, as modified by other changes adopted for API version 2. This struct will have 3 defined entries, and aggregates are free to include other entries to give more information to clients.
     205
     206The three required entries in the return structure are {{{code}}}, {{{value}}}, and {{{output}}}.
     207
     208 * {{{code}}}: An XML-RPC struct containing 3 sub elements. For details on this (adopted) proposal, see: https://openflow.stanford.edu/display/FOAM/AM+return+code+proposal
     209
     210In summary however:
     211
     212{{{
     213code {
     214  geni_code: XML-RPC integer, registered in an XML document off the GENI AM API page
     215  am_type: Optional: XML-RPC string, case insensitive, types in a registry (XML document) linked off the GENI AM API page
     216  am_code: Optional: XML-RPC integer
     217}
     218}}}
     219
     220Integers above are allowed to be negative.
     221
     222{{{am_type}}} and {{{am_code}}} are optional: AMs need not supply them and clients should not have to use them to understand the nature of the response.
     223They serve to further specify the nature of the return as indicated by {{{geni_code}}}
     224
     225Success is indicated by {{{geni_code}}} value of {{{0}}}
     226
     227Error codes and AM types are in an XML document off the GENI AM API page
     228
     229 * {{{value}}}: On success, this is required. Optional on failure or error. Object representing the successful return value. This will be the object previously returned by the function (for example the manifest RSpec for !CreateSliver, or the struct for !SliverStatus). The value is not defined on error, though aggregates are free to use it.
     230  * For !GetVersion, the {{{value}}} is an XML-RPC struct
     231  * For !ListResources, the {{{value}}} is an RSpec
     232  * For !CreateSliver, the {{{value}}} is an RSpec
     233  * For !RenewSliver, the {{{value}}} is a boolean
     234  * For !DeleteSliver, the {{{value}}} is a boolean
     235  * For !SliverStatus, the {{{value}}} is an XML-RPC struct
     236  * For Shutdown, the {{{value}}} is a boolean
     237 * {{{output}}}: On failure or error, this is required. Optional on success. This is a 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.
     238
     239Aggregates 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.
     240
     241GENI standard error codes will be documented on the GENI AM API Wiki page.
     242
     243Aggregates 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.
     244
     245Aggregates 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. Where the XML-RPC standard prescribes specific Faults, those will remain XML-RPC Faults.
     246
     247Aggregates are free to add additional return values 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, 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. We have not specified the format for advertising those extra return values in !GetVersion.
     248
     249For comparison, Orca functions return property lists internally. The ProtoGENI CMV2 API returns a struct with exactly these 3 values. ProtoGENI however uses a different range of return codes, and largely does not define the {{{value}}} slot on errors.
     250
     251For example, !SliverStatus could return on success:
     252{{{
     253{
     254  code: {
     255            geni_code: 0
     256        },
     257  value:
     258        {
     259            geni_urn: <sliver URN>
     260            geni_status: ready
     261            geni_resources: [ { geni_urn: <resource URN>
     262                                geni_status: ready
     263                                geni_error: ''},
     264                              { geni_urn: <resource URN>
     265                                geni_status: ready
     266                                geni_error: ''}
     267                            ]
     268        },
     269  output: <none>
     270}
     271}}}
     272
     273On failure, !DeleteSliver might return:
     274{{{
     275{
     276  code: {
     277        geni_code: 12
     278        }
     279  value: False
     280  output: 'No such slice here'
     281}
     282}}}
     283(That code and output are merely examples.)
     284
     285An exception:
     286At the top level, !GetVersion adds a required entry: 'geni_api'=2. This allows v1 clients to determine that they are indeed talking to a
     287GENI AM, but since the version is 2, that is why other function calls will fail with an XML-RPC Fault.
     288
     289==== Supporting multiple API versions ====
     290Aggregates are free to support multiple versions of the API. They do so by providing different URLs for each version of the API that they support.
     291Aggregates 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.)
     292Each server implementing the API must include all methods, including !GetVersion.
     293
     294This change modifies !GetVersion to include a new required member:
     295{{{
     296geni_api_versions: an XML-RPC struct containing 1+ entries of:
     297  Name: Integer - supported GENI AM API version
     298  Value: String - URL to the XML-RPC server implementing that version of the GENI AM API
     299}}}
     300
     301For example
     302{{{
     303geni_api_versions: {
     304  1: <URL>,
     305  2: <Local URL>,
     306   ...
     307}
     308}}}
     309
     310Where the entries indicate versions of the API supported, and URLs are absolute URLs where that version of the API is supported. (As per Change Set B above, this new member is a sub-structure to the {{{value}}} member.)
     311
     312==== Changes Summary: New Method Signatures ====
     313When taken together, the new method signatures would be:
     314
     315{{{
     316struct GetVersion(options=None)
     317Success Return:
     318{
     319  geni_api = 2
     320  code = {
     321       geni_code = 0
     322         }
     323  value
     324      {
     325        geni_api=2,
     326        geni_api_versions {
     327             2: <local URL>,
     328             <other versions and URLs as supported>
     329             }
     330        geni_request_rspec_versions [{
     331          type=GENI
     332          version=3
     333          schema=...
     334          namespace=....
     335          extensions []},
     336          <other version structs>]
     337        geni_ad_rspec_versions [{type, version, schema, namespace, extensions},]
     338      }
     339  output = <None>
     340}
     341}}}
     342
     343{{{
     344struct ListResources(string credentials[], struct options)
     345Success Return:
     346{
     347   code= {geni_code=0}
     348   value= <GENI v3 Ad or Manifest RSpec string>
     349   output = <None>
     350}
     351}}}
     352
     353{{{
     354struct CreateSliver(string slice_urn,
     355                    string credentials[],
     356                    <GENIv3 request RSpec schema compliant XML string> rspec,
     357                    struct users[],
     358                    struct options)
     359Success Return:
     360{
     361   code={geni_code=0}
     362   value= <GENI v3 Manifest RSpec string>
     363   output = <None>
     364}
     365}}}
     366
     367{{{
     368struct DeleteSliver(string slice_urn, string credentials[], struct options)
     369Success Return:
     370{
     371   code={geni_code=0}
     372   value= boolean
     373   output = <None>
     374}
     375}}}
     376
     377{{{
     378struct SliverStatus(string slice_urn, string credentials[], struct options)
     379Success Return:
     380{
     381   code={geni_code=0}
     382   value= struct (as defined in v1)
     383   output = <None>
     384}
     385}}}
     386
     387{{{
     388struct RenewSliver(string slice_urn,
     389                    string credentials[],
     390                    string expiration_time, struct options)
     391Success Return:
     392{
     393   code={geni_code=0}
     394   value= boolean
     395   output = <None>
     396}
     397}}}
     398
     399{{{
     400struct Shutdown(string slice_urn, string credentials[], struct options)
     401Success Return:
     402{
     403   code={geni_code=0}
     404   value= boolean
     405   output = <None>
     406}
     407}}}