Changes between Version 3 and Version 4 of GAPI_AM_API_DRAFT


Ignore:
Timestamp:
10/13/11 15:22:25 (13 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • GAPI_AM_API_DRAFT

    v3 v4  
    33= GENI Aggregate Manager API Draft Revisions =
    44
    5 This page documents DRAFT revisions to the GENI Aggregate Manager API, proposed for the next version of the API. Revisions documented here have been agreed to in discussions on the geni dev mailing list, and during at least on GEC, but not formally adopted. Well behaved aggregates will typically already implement these revisions.
     5This page documents DRAFT revisions to the GENI Aggregate Manager API, proposed for the next version of the API. As indicated below, many of the revisions documented here have been agreed to in discussions on the GENI developer mailing list, and during at least one GEC, but not formally adopted. Well behaved aggregates will typically already implement such revisions. Other revisions are in early discussions and subject to change or abandonment.
    66
    77The 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.
    88
    9 The current officially adopted version of the API is 1 and documented on the main API page [wiki:GAPI_AM_API here].
    10 
    11 This page documents proposed and generally accepted changes for AM API version 2.
    12   * As of June 2011, the latest software from ProtoGENI and SFA (as of code tag 1.0-24) comply with these changes.
    13   * Omni version 1.3 (released June 2011) adds client software support for these changes.
     9The current officially adopted version of the API is '''1''' and is documented on the main API page [wiki:GAPI_AM_API here].
     10
     11This page documents proposed changes for AM API version '''2'''. These changes are grouped into sets. API Version 2 will be the collection of changes from the change sets below which we next agree on. Change sets still under discussion will then be targeted at a future release.
     12 A. Agreed upon and generally implemented: RSpec related changes, specifying that RSpecs are XML following GENI standard schemas.
     13  * Since June 2011, the latest software from ProtoGENI and SFA (as of code tag 1.0-24) has complied with these changes.
     14  * Omni version 1.3 (released June 2011) added client software support for these changes.
     15 B. New and changing proposal: Supporting flexible arguments and returns. Specifically, adding a property list to all calls, and making all returns be a property list.
     16 C. Undefined proposal: Support for !UpdateSliver.
     17 D. Undefined: Support for clients adding slivers at an aggregate that already has 1 sliver for that slice, or deleting or renewing individual slivers.
     18 E. Undefined: Tickets, otherwise known as negotiated reservations.
    1419
    1520== Summary of Proposed Changes ==
    16  * Specify GENI RSpecs as complying with schemas documented as the ProtoGENI V2 RSpecs as documented [http://www.protogeni.net/trac/protogeni/wiki/RSpec here]
    17  * Include additional options in !GetResources and !ListResources to allow aggregates to support the GENI RSpecs in addition to their own native format.
     21=== Change Set A: RSpecs are XML documents following GENI schemas ===
     22This change set has been discussed and well behaved aggregates already implement this change.
     23
     24 * 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 here].
     25 * Include additional options in !GetVersion and !ListResources to allow aggregates to support the GENI RSpecs in addition to their own native format.
     26
     27=== Change Set B: Flexible arguments and returns ===
     28This change set is new, not implemented, and currently under discussion.
     29
     30 * 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.
     31 * Method returns are modified to return at least 3 name/value pairs, with arbitrary additional such pairs.
     32  * {{{code}}} is an integer, with non-0 indicating error.
     33  * {{{value}}} is the return value as specified in AM API V1 (RSpec, etc), and
     34  * {{{output}}} is a human readable indication of the nature of the return or error.
     35  * Aggregates are free to use other additional name/value pairs in the return struct.
     36
     37=== Change Set C: !UpdateSliver ===
     38
     39This change is TBD.
     40
     41=== Change Set D: Slivers and Slivergroups ===
     42
     43This change is TBD.
     44
     45=== Change Set E: Tickets ===
     46
     47This change is TBD.
    1848
    1949== Proposing Additional Changes ==
    … …  
    2656== Proposed Change Details ==
    2757
    28 === GENI Standard RSpecs ===
    29 At GEC10 [wiki:GEC10RSpec the GENI community agreed] that GENI RSpecs would be in the [http://www.protogeni.net/trac/protogeni/wiki/RSpec ProtoGENI V2 format]. 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].
     58=== Change Set A ===
     59
     60''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.'''
     61
     62''Note: Options in the geni_ namespace remain reserved, but not all GENI standard options need to be named with the geni_ prefix.''
     63
     64''Note: Changes described here have been discussed, are generally agreed upon, and are implemented at well behaved aggregates and clients.''
     65
     66==== Part 1: Standardized XML-based GENI RSpecs ====
     67At 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].
    3068
    3169For more information:
    32  * [http://www.protogeni.net/trac/protogeni/wiki/RSpec ProtoGENI V2 format]
     70 * [http://www.geni.net/resources/rspec/3 Official GENI V3 RSpec schemas]
     71 * [http://www.protogeni.net/trac/protogeni/wiki/RSpec GENI standard (was ProtoGENI V2) format]
    3372 * [http://www.protogeni.net/trac/protogeni/wiki/RSpecExtensions2 RSpec extension information]
    34  * [http://www.protogeni.net/trac/protogeni/wiki/RSpecSchema2 RSpec schemas]
     73 * [http://www.protogeni.net/trac/protogeni/wiki/RSpecSchema2 RSpec schemas listing]
    3574
    3675Specific changes include:
    3776 * !ListResources: Return value of !ListResources remains an [http://www.xmlrpc.com/spec XMLRPC] string, but its format and meaning are now proscribed.
    3877
    39  The return value is an RSpec matching the [http://www.protogeni.net/trac/protogeni/wiki/RSpec ProtoGENI V2] RSpec schema 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}}}.
    40 
    41 This RSpec will be a [http://www.protogeni.net/resources/rspec/2/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.protogeni.net/resources/rspec/2/manifest.xsd manifest RSpec], representing all resources allocated to that slice by this aggregate.
     78 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}}}.
     79
     80This 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.
    4281
    4382 * !CreateSliver: rspec argument remains an [http://www.xmlrpc.com/spec XMLRPC] string, but its format and meaning are now proscribed.
    4483
    4584  `rspec`::
    46     An RSpec matching the [http://www.protogeni.net/trac/protogeni/wiki/RSpec ProtoGENI V2] request RSpec [http://www.protogeni.net/resources/rspec/2/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 based on resources returned by a previous invocation of [wiki:GAPI_AM_API#ListResources ListResources].
     85    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].
    4786
    4887 * !CreateSliver: return value remains an [http://www.xmlrpc.com/spec XMLRPC] string, but its format and meaning are now proscribed.
    4988
    50  The return value is an RSpec matching the [http://www.protogeni.net/trac/protogeni/wiki/RSpec ProtoGENI V2] manifest RSpec [http://www.protogeni.net/resources/rspec/2/manifest.xsd schema] indicating the resources that were allocated to the slice. The result RSpec may contain additional information about the allocated resources.
    51 
    52 === New RSpec Version Options ===
    53 In 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 (ProtoGENI V2 schemas), we need new options to allow a client to request RSpecs in a particular format.
    54 
    55 Specifically, aggregates will advertise (in !GetVersion) the list of Advertisement and Request RSpec types they are willing to accept, as well as the default Advertisement RSpec type. And they will produce manifest RSpecs in a format matching the format of the !CreateSliver input request RSpec (e.g. return a manifest RSpec matching ProtoGENI V2 manifest schema when given a ProtoGENI V2 request RSpec, and a native !PlanetLab manifest RSpec when given a !PlanetLab request RSpec).
    56 
    57 ==== Contract details ====
     89 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.
     90
     91==== Part 2: New RSpec Version Options ====
     92In 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.
     93
     94Specifically, aggregates will advertise (in !GetVersion) the list of Advertisement and Request RSpec types they are willing to accept, as well as the default Advertisement RSpec type. 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).
     95
     96===== Contract details =====
    5897
    5998Aggregates 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.
    … …  
    61100If an aggregate advertises a particular {{{type}}}/{{{version}}} (optionally defined with a combination of {{{schema}}}, {{{namespace}}} and {{{extensions}}}) in the {{{ad_rspec_versions}}} attribute of !GetVersion, then it promises to send a correct Advertisement RSpec in response to a !ListResources call which supplies an {{{rspec_version}}} option containing that {{{type}}}/{{{version}}}. ({{{rspec_version}}} is a {{{struct}}} with 2 members, {{{type}}} and {{{version}}}. {{{type}}} and {{{version}}} are ''case-insensitive'' strings, matching those in {{{ad_rspec_versions}}}).
    62101
    63 If an Aggregate advertises a particular {{{type}}}/{{{version}}} (optionally defined with a combination of {{{schema}}}, {{{namespace}}} and {{{extensions}}}) in the {{{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 (ie a PGV2 request is answered with a PG V2 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 {{{rspec_version}}} option containing that supported {{{type}}}/{{{version}}}.
     102If an Aggregate advertises a particular {{{type}}}/{{{version}}} (optionally defined with a combination of {{{schema}}}, {{{namespace}}} and {{{extensions}}}) in the {{{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 {{{rspec_version}}} option containing that supported {{{type}}}/{{{version}}}.
    64103
    65104The !GetVersion attribute {{{default_ad_rspec}}} will be one of the values in the !GetVersion {{{ad_rspec_versions}}} array.
    66105
    67 ==== New !GetVersion required attributes ====
     106===== New !GetVersion required attributes =====
    68107
    69108Return the version of the GENI Aggregate API and RSpecs supported by this aggregate.
    … …  
    100139
    101140 `geni_api`::
    102     An integer indicating the revision of the Aggregate Manager API that an aggregate supports. The version of the API documented here is 2 (two).
     141    An integer indicating the revision of the Aggregate Manager API that an aggregate supports. This document (DRAFT revisions) describes API version 2 (two).
    103142
    104143 `request_rspec_versions`::
    … …  
    113152Elements used within {{{request_rspec_versions}}}, {{{ad_rspec_versions}}}, and {{{default_ad_rspec}}}:
    114153 `type`, `version`::
    115    Two ''case-insensitive'' strings which together comprise the type of RSpec. The RSpec `type` should be one of "protogeni", "sfa", "orca", "openflow", or "orbit" and `version` should be a type-specific version identifier as specified by the appropriate control framework.
     154   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.
    116155
    117156 `schema`::
    … …  
    122161
    123162 `extensions`::
    124    An array of cluster-specific strings denoting which extensions are supported. In the case of ProtoGENI, these are XML namespaces which denote the extension as a whole.
    125 
    126 Implementations 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. 
    127 
    128 This 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.
    129 
    130 ==== New !ListResources Option ====
     163   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.
     164
     165Implementations 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.
     166
     167This 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.
     168
     169===== New !ListResources Option =====
    131170!ListResources will take an additional option, {{{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 {{{ad_rspec_versions}}}.
    132171
    … …  
    142181
    143182 `options`::
    144     An [http://www.xmlrpc.com/spec XMLRPC] 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 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.
     183    An [http://www.xmlrpc.com/spec XMLRPC] 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.
    145184
    146185The following members are available for use in the options parameter. All aggregate managers are required to implement these options.
    … …  
    167206    If the aggregate cannot support the requested {{{type}}}/{{{version}}} (that pair is not listed in {{{ad_rspec_versions}}}), then the aggregate returns an Exception.
    168207
    169 ==== New !CreateSliver behavior ====
    170 If an Aggregate advertises a {{{type}}}/{{{version}}} pair in its {{{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 request in PGV2 schema is answered with a manifest in PG V2 format).
     208===== New !CreateSliver behavior =====
     209If an Aggregate advertises a {{{type}}}/{{{version}}} pair in its {{{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).
     210
     211=== Change Set B ===
     212''Note: This set of 2 distinct changes is currently under discussion and has gotten no unofficial or official agreement.''
     213
     214''Note: There are 2 parts to this change set. They could be adopted independently, but are described as going together. Additionally, they are described as cumulative to Change Set A above, but are independent.''
     215
     216==== Part 1: Additional options argument ====
     217Adding 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.
     218
     219Under this proposal, each method will take an argument which is a set of name-value pairs (an XMLRPC 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.
     220
     221Specifically, 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.
     222
     223Aggregates 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.
     224
     225In !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.
     226
     227==== Part 2: Richer return values ====
     228In AM API V1, method failures come back sometimes as XMLRPC 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.
     229
     230Allowing 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.
     231
     232This change will modify all methods to return an XMLRPC struct (aka property list) on any success, failure, and even on an error or for most exceptions. This struct will contain the return value from the previous revision of the AM API as an entry. This struct will have 3 defined entries, and aggregates are free to include other entries to give more information to clients.
     233
     234The three required entries in the return structure are {{{code}}}, {{{value}}}, and {{{option}}}:
     235 * {{{code}}}: An error code: integer, non-zero on error.
     236  * 0 = Success
     237  * <0 = XMLRPC required error codes
     238  * 1-1000 = GENI negotiated return codes (none so far)
     239  * 1001-2000 = ProtoGENI specific return codes
     240  * 2001-3000 = !PlanetLab specific return codes
     241  * 3001-4000 = Orca specific return codes
     242  * 4001-5000 = !OpenFlow specific return codes
     243  * others as needed
     244 * {{{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.
     245  * For !GetVersion, the {{{value}}} is an XMLRPC struct
     246  * For !ListResources, the {{{value}}} is an RSpec
     247  * For !CreateSliver, the {{{value}}} is an RSpec
     248  * For !RenewSliver, the {{{value}}} is a boolean
     249  * For !DeleteSliver, the {{{value}}} is a boolean
     250  * For !SliverStatus, the {{{value}}} is an XMLRPC struct
     251  * For Shutdown, the {{{value}}} is a boolean
     252 * {{{option}}}: 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.
     253
     254Aggregates 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.
     255
     256Aggregates 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.
     257
     258Aggregates should avoid raising an error (XMLRPC Fault), but rather should attempt to return this struct, providing any error messages and stack traces in the {{{output}}} field or other additional fields.
     259
     260For 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.
     261
     262For example, !SliverStatus could return on success:
     263{{{
     264{
     265  code: 0
     266  value:
     267{
     268  geni_urn: <sliver URN>
     269  geni_status: ready
     270  geni_resources: [ { geni_urn: <resource URN>
     271                      geni_status: ready
     272                      geni_error: ''},
     273                    { geni_urn: <resource URN>
     274                      geni_status: ready
     275                      geni_error: ''}
     276                  ]
     277}
     278
     279  option: <none>
     280}
     281}}}
     282
     283On failure, !DeleteSliver might return:
     284{{{
     285{
     286  code: 1
     287  value: False
     288  option: 'No such slice here'
     289}
     290}}}
     291(That code and option are merely examples.)
     292
     293An exception:
     294At the top level, !GetVersion adds a required entry: 'geni_api'=2. This allows V1 clients to determine that they are indeed talking to a
     295GENI AM, but since the version is 2, that is why other function calls will fail.
     296
     297==== Changes Summary: New Method Signatures ====
     298When taken together, the new method signatures would be:
     299
     300{{{
     301struct GetVersion(options=None)
     302Success Return:
     303{
     304  geni_api = 2
     305  code = 0
     306  value
     307      {
     308        geni_api=2
     309      }
     310  option = <None>
     311}
     312
     313struct ListResources(string credentials[], struct options)
     314Success Return:
     315{
     316   code=0
     317   value= <GENI V3 Ad or Manifest RSpec string>
     318   option = <None>
     319}
     320
     321struct CreateSliver(string slice_urn,
     322                    string credentials[],
     323                    <GENIV3 request RSpec schema compliant XML string> rspec,
     324                    struct users[],
     325                    struct options)
     326Success Return:
     327{
     328   code=0
     329   value= <GENI V3 Manifest RSpec string>
     330   option = <None>
     331}
     332
     333struct DeleteSliver(string slice_urn, string credentials[], struct options)
     334Success Return:
     335{
     336   code=0
     337   value= boolean
     338   option = <None>
     339}
     340
     341struct SliverStatus(string slice_urn, string credentials[], struct options)
     342Success Return:
     343{
     344   code=0
     345   value= struct (as defined in V1)
     346   option = <None>
     347}
     348
     349struct RenewSliver(string slice_urn,
     350                    string credentials[],
     351                    string expiration_time, struct options)
     352Success Return:
     353{
     354   code=0
     355   value= boolean
     356   option = <None>
     357}
     358
     359struct Shutdown(string slice_urn, string credentials[], struct options)
     360Success Return:
     361{
     362   code=0
     363   value= boolean
     364   option = <None>
     365}
     366}}}