Changes between Version 6 and Version 7 of GAPI_AM_API_DRAFT

Timestamp:

10/17/11 11:10:27 (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 encouraged to document any new options which they either accept or require in any method. 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.
+Aggregates 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.
+
+Aggregates are encouraged to document any new options which they accept in any method. 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 yet specified the format for advertising those extra options in !GetVersion'''
@@ -238 +240 @@
                             {
                                  type=String,
-                                 description="A useful but not critical option. This is a human parsable description.",
-                                 required=False
-                            },
+                                 description="A useful but not critical option. This is a human parsable description."
+                             },
                   myOtherNewOption:.....
                },