Changes between Version 4 and Version 5 of GAPI_AM_API_DRAFT

Timestamp:

10/14/11 09:52:10 (13 years ago)

Author:

Aaron Helsinger

Comment:

--

GAPI_AM_API_DRAFT

@@ -225 +225 @@
 In !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.
 
+Aggregates 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.
+
+'''We have not yet specified the format for advertising those extra options in !GetVersion'''
+
+A sample possible option advertisement in !GetVersion:
+{{{
+methodOptions:
+  {
+       GetVersion:
+               {
+                  myNewOption1:
+                            {
+                                 type=String,
+                                 description="A useful but not critical option. This is a human parsable description.",
+                                 required=False
+                            },
+                  myOtherNewOption:.....
+               },
+      ListResources....
+   }
+}}}
+
 ==== Part 2: Richer return values ====
 In 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.
@@ -230 +252 @@
 Allowing 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.
 
-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. 
+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. This struct will have 3 defined entries, and aggregates are free to include other entries to give more information to clients. 
 
 The three required entries in the return structure are {{{code}}}, {{{value}}}, and {{{option}}}:
@@ -256 +278 @@
 Aggregates 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.
 
-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.
+Aggregates 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.
 
 For 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.
@@ -306 +328 @@
   value
       {
-        geni_api=2
+        geni_api=2,
+        methodOptions:
+           {
+                <contents of this are TBD, as per above>
+           }
+        <lots of other options follow>
       }
   option = <None>