Changes between Version 19 and Version 20 of GAPI_AM_API_DRAFT


Ignore:
Timestamp:
11/04/11 10:19:51 (12 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • GAPI_AM_API_DRAFT

    v19 v20  
    3030 * 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.
    3131 * Method returns are modified to return at least 3 name/value pairs, with arbitrary additional such pairs.
    32   * {{{code}}} is an integer, with non-0 indicating error.
     32  * {{{code}}} indicates success or error return. There are 2 proposals for its structure (see below).
    3333  * {{{value}}} is the return value as specified in AM API v1 or as modified by Change Set A (RSpec, etc), and
    3434  * {{{output}}} is a human readable indication of the nature of the return or error.
     
    254254This 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.
    255255
    256 The three required entries in the return structure are {{{code}}}, {{{value}}}, and {{{output}}}:
     256The three required entries in the return structure are {{{code}}}, {{{value}}}, and {{{output}}}. There are 2 proposals for the structure of {{{code}}}.
     257
     258Proposal 1:
    257259 * {{{code}}}: An integer, non-zero on error.
    258260  * 0 = Success
     
    264266  * 4001-5000 = !OpenFlow specific return codes
    265267  * others as needed
     268
     269Proposal 2:
     270 * {{{code}}}: An XMLRPC string, of the form "<namespace string><separator><integer code>", where
     271  * <separator> is a colon (':')
     272  * <integer codes> MUST NOT be longer than 6 characters, and MUST be positive integers
     273  * <namespace string>:
     274   * Namespace names are case insensitive
     275   * Names MUST NOT be more than 16 characters
     276   * Names MUST use only ISO-8859-1 characters
     277   * Names are maintained at a registry linked off of the GENI AM API wiki page at geni.net
     278   * Names MUST NOT include the separator character
     279  * The namespace 'GENI' is reserved for error codes that are common across aggregates.
     280   * 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.
     281  * 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.
     282
     283Rationale for this proposal is available here: https://openflow.stanford.edu/display/FOAM/AM+return+code+proposal
     284
     285
    266286 * {{{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.
    267287  * For !GetVersion, the {{{value}}} is an XMLRPC struct
     
    281301Aggregates 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.
    282302
    283 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.
     303Aggregates 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.
    284304
    285305Aggregates 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.
     
    316336}
    317337}}}
    318 (That code and output are merely examples.)
     338(That code and output are merely examples. Not in particular that the example codes above use proposal 1 for the return code format.)
    319339
    320340An exception:
    321341At the top level, !GetVersion adds a required entry: 'geni_api'=2. This allows v1 clients to determine that they are indeed talking to a
    322342GENI AM, but since the version is 2, that is why other function calls will fail with an XMLRPC Fault.
    323 
    324 Note: A counter proposal in the community would make error codes be strings.
    325343
    326344Note: There is some discussion in the community about how aggregate managers might support multiple versions of this API, and advertise that capability to clients.