Changes between Version 19 and Version 20 of GAPI_AM_API_DRAFT

Timestamp:

11/04/11 10:19:51 (13 years ago)

Author:

Aaron Helsinger

Comment:

--

GAPI_AM_API_DRAFT

@@ -30 +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.
  * Method returns are modified to return at least 3 name/value pairs, with arbitrary additional such pairs. 
-  * {{{code}}} is an integer, with non-0 indicating error. 
+  * {{{code}}} indicates success or error return. There are 2 proposals for its structure (see below). 
   * {{{value}}} is the return value as specified in AM API v1 or as modified by Change Set A (RSpec, etc), and 
   * {{{output}}} is a human readable indication of the nature of the return or error. 
@@ -254 +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. 
 
-The three required entries in the return structure are {{{code}}}, {{{value}}}, and {{{output}}}:
+The three required entries in the return structure are {{{code}}}, {{{value}}}, and {{{output}}}. There are 2 proposals for the structure of {{{code}}}.
+
+Proposal 1:
  * {{{code}}}: An integer, non-zero on error. 
   * 0 = Success
@@ -264 +266 @@
   * 4001-5000 = !OpenFlow specific return codes
   * others as needed
+
+Proposal 2:
+ * {{{code}}}: An XMLRPC string, of the form "<namespace string><separator><integer code>", where
+  * <separator> is a colon (':')
+  * <integer codes> MUST NOT be longer than 6 characters, and MUST be positive integers
+  * <namespace string>:
+   * Namespace names are case insensitive
+   * Names MUST NOT be more than 16 characters
+   * Names MUST use only ISO-8859-1 characters
+   * Names are maintained at a registry linked off of the GENI AM API wiki page at geni.net
+   * Names MUST NOT include the separator character
+  * The namespace 'GENI' is reserved for error codes that are common across aggregates.
+   * The GENI namespace SHALL contain errors which are common across multiple (although not necessarily all) aggregates. If the GENI namespace has a code which articulates the error you are returning, you MUST use this code instead of one from your own namespace.
+  * Success MUST be indicated by the use of 0 in the GENI namespace: "GENI:0". There is currently no way to indicate "degrees" of success with qualifiers - if you want to reflect this it should be in an error.
+
+Rationale for this proposal is available here: https://openflow.stanford.edu/display/FOAM/AM+return+code+proposal
+
+
  * {{{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.
   * For !GetVersion, the {{{value}}} is an XMLRPC struct
@@ -281 +301 @@
 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) 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.
+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. Where the XMLRPC standard prescribes specific Faults, those will remain XMLRPC Faults.
 
 Aggregates are free to add additional return values to support aggregate or resource specific functionality, or to innovate within the bounds of the AM API. Aggregates are encouraged to document any such new return values which they return, 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 return values. Alternatively or additionally, aggregates may document return values as part of their return from !GetVersion. We have not specified the format for advertising those extra return values in !GetVersion.
@@ -316 +336 @@
 }
 }}}
-(That code and output are merely examples.)
+(That code and output are merely examples. Not in particular that the example codes above use proposal 1 for the return code format.)
 
 An exception:
 At the top level, !GetVersion adds a required entry: 'geni_api'=2. This allows v1 clients to determine that they are indeed talking to a
 GENI AM, but since the version is 2, that is why other function calls will fail with an XMLRPC Fault.
-
-Note: A counter proposal in the community would make error codes be strings.
 
 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.