Changes between Version 4 and Version 5 of GAPI_AM_API_DRAFT


Ignore:
Timestamp:
10/14/11 09:52:10 (8 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • GAPI_AM_API_DRAFT

    v4 v5  
    225225In !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.
    226226
     227Aggregates are expected to document any new options which they either accept or require in any method, 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.
     228
     229'''We have not yet specified the format for advertising those extra options in !GetVersion'''
     230
     231A sample possible option advertisement in !GetVersion:
     232{{{
     233methodOptions:
     234  {
     235       GetVersion:
     236               {
     237                  myNewOption1:
     238                            {
     239                                 type=String,
     240                                 description="A useful but not critical option. This is a human parsable description.",
     241                                 required=False
     242                            },
     243                  myOtherNewOption:.....
     244               },
     245      ListResources....
     246   }
     247}}}
     248
    227249==== Part 2: Richer return values ====
    228250In 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.
     
    230252Allowing 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.
    231253
    232 This 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.
     254This 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. This struct will have 3 defined entries, and aggregates are free to include other entries to give more information to clients.
    233255
    234256The three required entries in the return structure are {{{code}}}, {{{value}}}, and {{{option}}}:
     
    256278Aggregates 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.
    257279
    258 Aggregates 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.
     280Aggregates should avoid raising an error (XMLRPC Fault) for application layer errors or any other cases where the XMLRPC 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.
    259281
    260282For 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.
     
    306328  value
    307329      {
    308         geni_api=2
     330        geni_api=2,
     331        methodOptions:
     332           {
     333                <contents of this are TBD, as per above>
     334           }
     335        <lots of other options follow>
    309336      }
    310337  option = <None>