Changes between Version 21 and Version 22 of GAPI_AM_API_DRAFT


Ignore:
Timestamp:
11/04/11 17:09:46 (12 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • GAPI_AM_API_DRAFT

    v21 v22  
    99The current officially adopted version of the API is '''1''' and is documented on the main API page [wiki:GAPI_AM_API here].
    1010
    11 This 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.
     11This page documents changes for AM API version '''2''' and proposed changes for AM API version '''3''' or later. These changes are grouped into sets. API Version 2 will be change sets A and B below, as agreed to at GEC12. Other change sets are still under discussion and will be targeted at a future release.
     12
    1213 A. To be in version 2, agreed upon and generally implemented: RSpec related changes, specifying that RSpecs are XML following GENI standard schemas.
     14  * This set was modified slightly at the coding sprint session of GEC12 - that change is not yet implemented
    1315  * Since June 2011, the latest software from ProtoGENI and SFA (as of code tag 1.0-24) has complied with these changes.
    1416  * Omni version 1.3 (released June 2011) added client software support for these changes.
    15  B. To be in version 2, subject to ongoing discussion: Supporting flexible arguments and returns. Specifically, adding a property list to all calls, and making all returns be a property list.
     17 B. To be in version 2: Supporting flexible arguments and returns. Specifically, adding a property list to all calls, and making all returns be a property list.
    1618 C. New and changing proposal: Add a new method: !UpdateSliver
    1719 D. Undefined: Support for clients manipulating individual slivers or groups of slivers at an aggregate
     
    2022== Summary of Proposed Changes ==
    2123=== Change Set A: RSpecs are XML documents following GENI schemas ===
    22 This change set has been discussed and well behaved aggregates already implement this change. The community has agreed to include this change in version 2 of this API.
     24'''Note''': At the GEC12 coding sprint, this change set was modified slightly from that which is widely implemented. This change
     25 - removed the {{{default_ad_rspec}}} value from getVersion
     26 - made the {{{rspec_version}}} argument to listResources required
     27 - renamed the other return values from getVersion to use the {{{geni_}}} naming prefix
     28
     29Other parts of this change set have been discussed and well behaved aggregates already implement them. The community has agreed to include this change in version 2 of this API.
    2330
    2431 * 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].
     
    2633
    2734=== Change Set B: Flexible arguments and returns ===
    28 This change set is new, not implemented, and remains under discussion. At GEC12 the community agreed to include Part 1 in version 2 of the API, but several small points of Part 2 remain under discussion.
     35This change set is new and not implemented, but was adopted at GEC12 for inclusion in AM API version 2.
    2936
    3037 * 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.
    3138 * Method returns are modified to return at least 3 name/value pairs, with arbitrary additional such pairs.
    32   * {{{code}}} indicates success or error return. There are 2 proposals for its structure (see below).
     39  * {{{code}}} indicates success or error return. This itself is an XMLRPC struct, whose content is described below.
    3340  * {{{value}}} is the return value as specified in AM API v1 or as modified by Change Set A (RSpec, etc), and
    3441  * {{{output}}} is a human readable indication of the nature of the return or error.
     
    6067
    6168=== Change Set A ===
     69
     70'''Note''': At the GEC12 coding sprint, this change set was modified slightly from that which is widely implemented. This change
     71 - removed the {{{default_ad_rspec}}} value from getVersion
     72 - made the {{{rspec_version}}} argument to listResources required
     73 - renamed the other return values from getVersion to use the {{{geni_}}} naming prefix
    6274
    6375''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.'''
     
    95107In 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.
    96108
    97 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 GENI v3 manifest RSpec when given a GENI v3 request RSpec, and a native !PlanetLab manifest RSpec when given a !PlanetLab request RSpec).
     109Specifically, 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).
    98110
    99111===== Contract details =====
     
    101113Aggregates 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.
    102114
    103 If 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}}}).
    104 
    105 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 (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}}}.
    106 
    107 The !GetVersion attribute {{{default_ad_rspec}}} will be one of the values in the !GetVersion {{{ad_rspec_versions}}} array.
     115If 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 {{{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 {{{geni_ad_rspec_versions}}}).
     116
     117If 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}}}.
    108118
    109119===== New !GetVersion required attributes =====
     
    120130{
    121131  int geni_api;
    122   array request_rspec_versions of {
     132  array geni_request_rspec_versions of {
    123133    string type;
    124134    string version;
     
    127137    array extensions of string;
    128138  };
    129   array ad_rspec_versions of {
     139  array geni_ad_rspec_versions of {
    130140    string type;
    131141    string version;
     
    134144    array extensions of string;
    135145  };
    136   default_ad_rspec of {
    137     string type;
    138     string version;
    139   };
    140146}
    141147}}}
     
    144150    An integer indicating the revision of the Aggregate Manager API that an aggregate supports. This document (DRAFT revisions) describes API version 2 (two).
    145151
    146  `request_rspec_versions`::
     152 `geni_request_rspec_versions`::
    147153   An array of data structures indicating the RSpec types accepted by this AM in a request.
    148154
    149  `ad_rspec_versions`::
     155 `geni_ad_rspec_versions`::
    150156   An array of data structures indicating what types of RSpec advertisements may be produced by this AM in !ListResources.
    151157
    152  `default_ad_rspec`::
    153    A data structure indicating the default type of advertisement RSpec produced by this AM in !ListResources. Matches one of the values from {{{ad_rspec_versions}}}
    154 
    155 Elements used within {{{request_rspec_versions}}}, {{{ad_rspec_versions}}}, and {{{default_ad_rspec}}}:
     158Elements used within {{{geni_request_rspec_versions}}} and {{{geni_ad_rspec_versions}}}:
    156159 `type`, `version`::
    157160   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.
     
    171174
    172175===== New !ListResources Option =====
    173 !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}}}.
     176!ListResources will take an additional ''required'' 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 {{{geni_ad_rspec_versions}}}.
    174177
    175178Specifics:
     
    203206
    204207 `rspec_version`::
    205     An [http://www.xmlrpc.com/spec XMLRPC] 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 {{{ad_rspec_versions}}} as returned by !GetVersion at this aggregate.
    206 
    207     If this option is not included in the request, then the returned RSpec will be of the type specified in {{{default_ad_rspec}}}. That 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 {{{default_ad_rspec}}}, but in manifest format.
    208 
    209     If the aggregate cannot support the requested {{{type}}}/{{{version}}} (that pair is not listed in {{{ad_rspec_versions}}}), then the aggregate returns an Exception.
     208    An [http://www.xmlrpc.com/spec XMLRPC] 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 an geni_code 1 ('Bad Arguments') if it is missing.
     209
     210    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 {{{rspec_version}}}, but in manifest format.
     211
     212    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).
    210213
    211214===== New !CreateSliver behavior =====
    212 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 GENI v3 standard request is answered with a GENI v3 manifest).
     215If 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).
    213216
    214217=== Change Set B ===
    215 ''Note: This set of 2 distinct changes is currently under discussion. Part 1 was approved for inclusion in AM API v2 at GEC12. Part 2 got general approval at GEC12, but there are several open questions that remain under discussion.''
     218''Note: This set of 2 distinct changes was discussed and adopted at GEC12 for inclusion in AM API version 2, but is not yet implemented.''
    216219
    217220==== Part 1: Additional options argument ====
     
    228231Aggregates 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.
    229232
    230 Aggregates are encouraged to document any new options which they accept in any method, 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 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. We have not specified the format for advertising those extra options in !GetVersion.
    231 
    232 A sample possible option advertisement in !GetVersion:
    233 {{{
    234 methodOptions:
    235   {
    236        GetVersion:
    237                {
    238                   verbose:
    239                             {
    240                                  type=boolean,
    241                                  description="True means supply gory details on server internal versions. This is a human parsable description."
    242                              },
    243                   myOtherNewOption:.....
    244                },
    245       ListResources....
    246    }
    247 }}}
     233Aggregates 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.
    248234
    249235==== Part 2: Richer return values ====
     
    252238Allowing 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.
    253239
    254 This change will modify all methods to return an XMLRPC struct (aka property list) on any application layer success, failure, and even on an error or for most exceptions. Note that a malformed XMLRPC request should still raise an XMLRPC Fault, and other Faults dictated by the XMLRPC specification should still be raised. This struct will contain the return value from the previous revision of the AM API as an entry (or the return value as modified by Change Set A if adopted). This struct will have 3 defined entries, and aggregates are free to include other entries to give more information to clients.
    255 
    256 The three required entries in the return structure are {{{code}}}, {{{value}}}, and {{{output}}}. There are 2 proposals for the structure of {{{code}}}.
    257 
    258 Proposal 1:
    259  * {{{code}}}: An integer, non-zero on error.
    260   * 0 = Success
    261   * <0 = XMLRPC required error codes
    262   * 1-1000 = GENI negotiated return codes (none so far)
    263   * 1001-2000 = ProtoGENI specific return codes
    264   * 2001-3000 = !PlanetLab specific return codes
    265   * 3001-4000 = Orca specific return codes
    266   * 4001-5000 = !OpenFlow specific return codes
    267   * others as needed
    268 
    269 Proposal 2:
    270  * {{{code}}}: An XMLRPC string, of the form "<namespace string><separator><integer code>". For details on this proposal, see: https://openflow.stanford.edu/display/FOAM/AM+return+code+proposal
     240This change will modify all methods to return an XMLRPC struct (aka property list) on any application layer success, failure, and even on an error or for most exceptions. Note that a malformed XMLRPC request should still raise an XMLRPC Fault, and other Faults dictated by the XMLRPC 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.
     241
     242The three required entries in the return structure are {{{code}}}, {{{value}}}, and {{{output}}}.
     243
     244 * {{{code}}}: An XMLRPC struct containing 3 sub elements. For details on this (adopted) proposal, see: https://openflow.stanford.edu/display/FOAM/AM+return+code+proposal
     245
     246In summary however:
     247
     248{{{
     249code {
     250  geni_code: XMLRPC integer, registered in an XML document off the GENI AM API page
     251  am_type: XMLRPC string, case insensitive, types in a registry (XML document) linked off the GENI AM API page
     252  am_code: XMLRPC integer
     253}
     254}}}
     255
     256Integers above are allowed to be negative
     257
     258{{{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.
     259They serve to further specify the nature of the return as indicated by {{{geni_code}}}
     260
     261Success is indicated by {{{geni_code}}} value of 0
     262
     263Error codes and AM types are in an XML document off the GENI AM API page
    271264
    272265 * {{{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.
     
    283276
    284277GENI standard error codes will be documented on the GENI AM API Wiki page.
    285 '''TODO''': The community must standardize on some GENI-wide error codes.
    286278
    287279Aggregates 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.
     
    296288{{{
    297289{
    298   code: 0
     290  code: {
     291       geni_code: 0
     292        },
    299293  value:
    300294{
     
    317311{{{
    318312{
    319   code: 1
     313  code: {
     314        geni_code: 12
     315        }
    320316  value: False
    321317  output: 'No such slice here'
    322318}
    323319}}}
    324 (That code and output are merely examples. Not in particular that the example codes above use proposal 1 for the return code format.)
     320(That code and output are merely examples.)
    325321
    326322An exception:
     
    328324GENI AM, but since the version is 2, that is why other function calls will fail with an XMLRPC Fault.
    329325
    330 Note: There is some discussion in the community about how aggregate managers might support multiple versions of this API, and advertise that capability to clients.
     326==== Supporting multiple API versions ====
     327Aggregates 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.
     328Aggregates 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.)
     329Each server implementing the API must include all methods, including getVersion.
     330
     331This change modifies getVersion to include a new required member:
     332geni_api_versions: {
     333  1: <URL>,
     334  2: <URL>,
     335   ...
     336}
     337
     338Where 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.)
    331339
    332340==== Changes Summary: New Method Signatures ====
     
    338346{
    339347  geni_api = 2
    340   code = 0
     348  code = {
     349       geni_code = 0
     350         }
    341351  value
    342352      {
    343353        geni_api=2,
    344         methodOptions:
    345            {
    346                 <contents of this are TBD, as per above>
    347            }
    348         <lots of other options follow>
     354        geni_api_versions {
     355             2: <local URL>,
     356             <other versions and URLs as supported>
     357             }
     358        geni_request_rspec_versions [{
     359          type=GENI
     360          version=3
     361          schema=...
     362          namespace=....
     363          extensions []},
     364          <other version structs>]
     365        geni_ad_rspec_versions [{type, version, schema, namespace, extensions},]
    349366      }
    350367  output = <None>
     
    354371Success Return:
    355372{
    356    code=0
     373   code= {geni_code=0}
    357374   value= <GENI v3 Ad or Manifest RSpec string>
    358375   output = <None>
     
    366383Success Return:
    367384{
    368    code=0
     385   code={geni_code=0}
    369386   value= <GENI v3 Manifest RSpec string>
    370387   output = <None>
     
    374391Success Return:
    375392{
    376    code=0
     393   code={geni_code=0}
    377394   value= boolean
    378395   output = <None>
     
    382399Success Return:
    383400{
    384    code=0
     401   code={geni_code=0}
    385402   value= struct (as defined in v1)
    386403   output = <None>
     
    392409Success Return:
    393410{
    394    code=0
     411   code={geni_code=0}
    395412   value= boolean
    396413   output = <None>
     
    400417Success Return:
    401418{
    402    code=0
     419   code={geni_code=0}
    403420   value= boolean
    404421   output = <None>