Changes between Version 21 and Version 22 of GAPI_AM_API_DRAFT
- Timestamp:
- 11/04/11 17:09:46 (12 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
GAPI_AM_API_DRAFT
v21 v22 9 9 The current officially adopted version of the API is '''1''' and is documented on the main API page [wiki:GAPI_AM_API here]. 10 10 11 This page documents proposed changes for AM API version '''2'''. These changes are grouped into sets. API Version 2 will be the collection of changes from the change sets below which we next agree on. Change sets still under discussion will then be targeted at a future release. 11 This page documents changes for AM API version '''2''' and proposed changes for AM API version '''3''' or later. These changes are grouped into sets. API Version 2 will be change sets A and B below, as agreed to at GEC12. Other change sets are still under discussion and will be targeted at a future release. 12 12 13 A. To be in version 2, agreed upon and generally implemented: RSpec related changes, specifying that RSpecs are XML following GENI standard schemas. 14 * This set was modified slightly at the coding sprint session of GEC12 - that change is not yet implemented 13 15 * Since June 2011, the latest software from ProtoGENI and SFA (as of code tag 1.0-24) has complied with these changes. 14 16 * Omni version 1.3 (released June 2011) added client software support for these changes. 15 B. To be in version 2 , subject to ongoing discussion: Supporting flexible arguments and returns. Specifically, adding a property list to all calls, and making all returns be a property list.17 B. To be in version 2: Supporting flexible arguments and returns. Specifically, adding a property list to all calls, and making all returns be a property list. 16 18 C. New and changing proposal: Add a new method: !UpdateSliver 17 19 D. Undefined: Support for clients manipulating individual slivers or groups of slivers at an aggregate … … 20 22 == Summary of Proposed Changes == 21 23 === Change Set A: RSpecs are XML documents following GENI schemas === 22 This change set has been discussed and well behaved aggregates already implement this change. The community has agreed to include this change in version 2 of this API. 24 '''Note''': At the GEC12 coding sprint, this change set was modified slightly from that which is widely implemented. This change 25 - removed the {{{default_ad_rspec}}} value from getVersion 26 - made the {{{rspec_version}}} argument to listResources required 27 - renamed the other return values from getVersion to use the {{{geni_}}} naming prefix 28 29 Other parts of this change set have been discussed and well behaved aggregates already implement them. The community has agreed to include this change in version 2 of this API. 23 30 24 31 * Specify that GENI RSpecs comply with GENI standard XML schemas as posted at http://www.geni.net/resources/rspec. GENI RSpec v3 is what was the ProtoGENI v2 schemas as documented [http://www.protogeni.net/trac/protogeni/wiki/RSpec here]. … … 26 33 27 34 === Change Set B: Flexible arguments and returns === 28 This change set is new , not implemented, and remains under discussion. At GEC12 the community agreed to include Part 1 in version 2 of the API, but several small points of Part 2 remain under discussion.35 This change set is new and not implemented, but was adopted at GEC12 for inclusion in AM API version 2. 29 36 30 37 * 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. 31 38 * Method returns are modified to return at least 3 name/value pairs, with arbitrary additional such pairs. 32 * {{{code}}} indicates success or error return. Th ere are 2 proposals for its structure (see below).39 * {{{code}}} indicates success or error return. This itself is an XMLRPC struct, whose content is described below. 33 40 * {{{value}}} is the return value as specified in AM API v1 or as modified by Change Set A (RSpec, etc), and 34 41 * {{{output}}} is a human readable indication of the nature of the return or error. … … 60 67 61 68 === Change Set A === 69 70 '''Note''': At the GEC12 coding sprint, this change set was modified slightly from that which is widely implemented. This change 71 - removed the {{{default_ad_rspec}}} value from getVersion 72 - made the {{{rspec_version}}} argument to listResources required 73 - renamed the other return values from getVersion to use the {{{geni_}}} naming prefix 62 74 63 75 ''Note: The change to GENI standard RSpec schemas originally referenced ProtoGENI v2 RSpec schemas, hosted at www.protogeni.net. These schemas have now been re-branded as GENI v3 RSpec schemas and are hosted at http://www.geni.net/resources/rspec/3.''' … … 95 107 In order to allow aggregates to support both a native RSpec format (e.g. the standard !PlanetLab / SFA RSpecs) as well as the GENI-standard format (GENI v3, was ProtoGENI v2), we need new options to allow a client to request RSpecs in a particular format. 96 108 97 Specifically, aggregates will advertise (in !GetVersion) the list of Advertisement and Request RSpec types they are willing to accept , as well as the default Advertisement RSpec type. And they will produce manifest RSpecs in a format matching the format of the !CreateSliver input request RSpec (e.g. return a GENI v3 manifest RSpec when given a GENI v3 request RSpec, and a native !PlanetLab manifest RSpec when given a !PlanetLab request RSpec).109 Specifically, aggregates will advertise (in !GetVersion) the list of Advertisement and Request RSpec types they are willing to accept. And they will produce manifest RSpecs in a format matching the format of the !CreateSliver input request RSpec (e.g. return a GENI v3 manifest RSpec when given a GENI v3 request RSpec, and a native !PlanetLab manifest RSpec when given a !PlanetLab request RSpec). 98 110 99 111 ===== Contract details ===== … … 101 113 Aggregates advertise the {{{type}}} and {{{version}}} of RSpec formats that they support. If available, they specify the {{{schema}}}, {{{namespace}}} and {{{extensions}}} combination which is the authoritative definition of that format. Clients of the API should understand that combination in order to know how to understand the resources available at that aggregate. 102 114 103 If an aggregate advertises a particular {{{type}}}/{{{version}}} (optionally defined with a combination of {{{schema}}}, {{{namespace}}} and {{{extensions}}}) in the {{{ad_rspec_versions}}} attribute of !GetVersion, then it promises to send a correct Advertisement RSpec in response to a !ListResources call which supplies an {{{rspec_version}}} option containing that {{{type}}}/{{{version}}}. ({{{rspec_version}}} is a {{{struct}}} with 2 members, {{{type}}} and {{{version}}}. {{{type}}} and {{{version}}} are ''case-insensitive'' strings, matching those in {{{ad_rspec_versions}}}). 104 105 If an Aggregate advertises a particular {{{type}}}/{{{version}}} (optionally defined with a combination of {{{schema}}}, {{{namespace}}} and {{{extensions}}}) in the {{{request_rspec_versions}}} attribute of !GetVersion then it promises to correctly honor a !CreateSliver call containing a request RSpec in the given format, and then to return a Manifest RSpec in the corresponding format (i.e. a GENI format request is answered with a GENI format manifest). The aggregate also promises to send a correctly formatted Manifest RSpec in response to a !ListResources call which supplies a valid {{{geni_slice_urn}}} option and an {{{rspec_version}}} option containing that supported {{{type}}}/{{{version}}}. 106 107 The !GetVersion attribute {{{default_ad_rspec}}} will be one of the values in the !GetVersion {{{ad_rspec_versions}}} array. 115 If an aggregate advertises a particular {{{type}}}/{{{version}}} (optionally defined with a combination of {{{schema}}}, {{{namespace}}} and {{{extensions}}}) in the {{{geni_ad_rspec_versions}}} attribute of !GetVersion, then it promises to send a correct Advertisement RSpec in response to a !ListResources call which supplies an {{{rspec_version}}} option containing that {{{type}}}/{{{version}}}. ({{{rspec_version}}} is a {{{struct}}} with 2 members, {{{type}}} and {{{version}}}. {{{type}}} and {{{version}}} are ''case-insensitive'' strings, matching those in {{{geni_ad_rspec_versions}}}). 116 117 If an Aggregate advertises a particular {{{type}}}/{{{version}}} (optionally defined with a combination of {{{schema}}}, {{{namespace}}} and {{{extensions}}}) in the {{{geni_request_rspec_versions}}} attribute of !GetVersion then it promises to correctly honor a !CreateSliver call containing a request RSpec in the given format, and then to return a Manifest RSpec in the corresponding format (i.e. a GENI format request is answered with a GENI format manifest). The aggregate also promises to send a correctly formatted Manifest RSpec in response to a !ListResources call which supplies a valid {{{geni_slice_urn}}} option and an {{{geni_rspec_version}}} option containing that supported {{{type}}}/{{{version}}}. 108 118 109 119 ===== New !GetVersion required attributes ===== … … 120 130 { 121 131 int geni_api; 122 array request_rspec_versions of {132 array geni_request_rspec_versions of { 123 133 string type; 124 134 string version; … … 127 137 array extensions of string; 128 138 }; 129 array ad_rspec_versions of {139 array geni_ad_rspec_versions of { 130 140 string type; 131 141 string version; … … 134 144 array extensions of string; 135 145 }; 136 default_ad_rspec of {137 string type;138 string version;139 };140 146 } 141 147 }}} … … 144 150 An integer indicating the revision of the Aggregate Manager API that an aggregate supports. This document (DRAFT revisions) describes API version 2 (two). 145 151 146 ` request_rspec_versions`::152 `geni_request_rspec_versions`:: 147 153 An array of data structures indicating the RSpec types accepted by this AM in a request. 148 154 149 ` ad_rspec_versions`::155 `geni_ad_rspec_versions`:: 150 156 An array of data structures indicating what types of RSpec advertisements may be produced by this AM in !ListResources. 151 157 152 `default_ad_rspec`:: 153 A data structure indicating the default type of advertisement RSpec produced by this AM in !ListResources. Matches one of the values from {{{ad_rspec_versions}}} 154 155 Elements used within {{{request_rspec_versions}}}, {{{ad_rspec_versions}}}, and {{{default_ad_rspec}}}: 158 Elements used within {{{geni_request_rspec_versions}}} and {{{geni_ad_rspec_versions}}}: 156 159 `type`, `version`:: 157 160 Two ''case-insensitive'' strings which together comprise the type of RSpec. The RSpec `type` should be one of "geni", "protogeni", "sfa", "orca", "openflow", or "orbit" and `version` should be a type-specific version identifier as specified by the appropriate control framework. The "geni" type is reserved for GENI standard format RSpecs, following the schemas hosted at www.geni.net. … … 171 174 172 175 ===== New !ListResources Option ===== 173 !ListResources will take an additional option, {{{rspec_version}}}, allowing a user to request an Advertisement or Manifest Rspec in a particular format. This struct must contain a {{{type}}} and {{{version}}} matching one of this Aggregate's advertised {{{ad_rspec_versions}}}.176 !ListResources will take an additional ''required'' option, {{{rspec_version}}}, allowing a user to request an Advertisement or Manifest Rspec in a particular format. This struct must contain a {{{type}}} and {{{version}}} matching one of this Aggregate's advertised {{{geni_ad_rspec_versions}}}. 174 177 175 178 Specifics: … … 203 206 204 207 `rspec_version`:: 205 An [http://www.xmlrpc.com/spec XMLRPC] struct indicating the type and version of Advertisement or Manifest RSpec to return. The struct contains 2 members, {{{type}}} and {{{version}}}. {{{type}}} and {{{version}}} are ''case-insensitive'' strings, matching those in {{{ ad_rspec_versions}}} as returned by !GetVersion at this aggregate.206 207 If this option is not included in the request, then the returned RSpec will be of the type specified in {{{default_ad_rspec}}}. That Rspec will be an Advertisement RSpec when no {{{geni_slice_urn}}} option is supplied. When a valid {{{geni_slice_urn}}} option is supplied, the returned RSpec will be a Manifest RSpec of the type corresponding to {{{default_ad_rspec}}}, but in manifest format.208 209 If the aggregate cannot support the requested {{{type}}}/{{{version}}} (that pair is not listed in {{{ ad_rspec_versions}}}), then the aggregate returns an Exception.208 An [http://www.xmlrpc.com/spec XMLRPC] struct indicating the type and version of Advertisement or Manifest RSpec to return. The struct contains 2 members, {{{type}}} and {{{version}}}. {{{type}}} and {{{version}}} are ''case-insensitive'' strings, matching those in {{{geni_ad_rspec_versions}}} as returned by !GetVersion at this aggregate. This option is ''required'', and aggregates are expected to return an geni_code 1 ('Bad Arguments') if it is missing. 209 210 The returned Rspec will be an Advertisement RSpec when no {{{geni_slice_urn}}} option is supplied. When a valid {{{geni_slice_urn}}} option is supplied, the returned RSpec will be a Manifest RSpec of the type corresponding to {{{rspec_version}}}, but in manifest format. 211 212 If the aggregate cannot support the requested {{{type}}}/{{{version}}} (that pair is not listed in {{{geni_ad_rspec_versions}}}), then the aggregate returns an error 13 (UNSUPPORTED). 210 213 211 214 ===== New !CreateSliver behavior ===== 212 If an Aggregate advertises a {{{type}}}/{{{version}}} pair in its {{{ request_rspec_versions}}} as returned by !GetVersion, then it promises to correctly honor a !CreateSliver call containing a request RSpec in the given format, and then to return a Manifest RSpec in the corresponding format (ie a GENI v3 standard request is answered with a GENI v3 manifest).215 If an Aggregate advertises a {{{type}}}/{{{version}}} pair in its {{{geni_request_rspec_versions}}} as returned by !GetVersion, then it promises to correctly honor a !CreateSliver call containing a request RSpec in the given format, and then to return a Manifest RSpec in the corresponding format (ie a GENI v3 standard request is answered with a GENI v3 manifest). 213 216 214 217 === Change Set B === 215 ''Note: This set of 2 distinct changes is currently under discussion. Part 1 was approved for inclusion in AM API v2 at GEC12. Part 2 got general approval at GEC12, but there are several open questions that remain under discussion.''218 ''Note: This set of 2 distinct changes was discussed and adopted at GEC12 for inclusion in AM API version 2, but is not yet implemented.'' 216 219 217 220 ==== Part 1: Additional options argument ==== … … 228 231 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. 229 232 230 Aggregates are encouraged to document any new options which they accept in any method, 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 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 specified the format for advertising those extra options in !GetVersion. 231 232 A sample possible option advertisement in !GetVersion: 233 {{{ 234 methodOptions: 235 { 236 GetVersion: 237 { 238 verbose: 239 { 240 type=boolean, 241 description="True means supply gory details on server internal versions. This is a human parsable description." 242 }, 243 myOtherNewOption:..... 244 }, 245 ListResources.... 246 } 247 }}} 233 Aggregates are encouraged to document any new options which they accept in any method, to bootstrap coordination with clients, and provide documentation for human experimenters. This API does not specify how aggregates provide that documentation. 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. 248 234 249 235 ==== Part 2: Richer return values ==== … … 252 238 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. 253 239 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. 255 256 The three required entries in the return structure are {{{code}}}, {{{value}}}, and {{{output}}}. There are 2 proposals for the structure of {{{code}}}. 257 258 Proposal 1: 259 * {{{code}}}: An integer, non-zero on error. 260 * 0 = Success 261 * <0 = XMLRPC required error codes 262 * 1-1000 = GENI negotiated return codes (none so far) 263 * 1001-2000 = ProtoGENI specific return codes 264 * 2001-3000 = !PlanetLab specific return codes 265 * 3001-4000 = Orca specific return codes 266 * 4001-5000 = !OpenFlow specific return codes 267 * others as needed 268 269 Proposal 2: 270 * {{{code}}}: An XMLRPC string, of the form "<namespace string><separator><integer code>". For details on this proposal, see: https://openflow.stanford.edu/display/FOAM/AM+return+code+proposal 240 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, as modified by other changes adopted for API version 2. This struct will have 3 defined entries, and aggregates are free to include other entries to give more information to clients. 241 242 The three required entries in the return structure are {{{code}}}, {{{value}}}, and {{{output}}}. 243 244 * {{{code}}}: An XMLRPC struct containing 3 sub elements. For details on this (adopted) proposal, see: https://openflow.stanford.edu/display/FOAM/AM+return+code+proposal 245 246 In summary however: 247 248 {{{ 249 code { 250 geni_code: XMLRPC integer, registered in an XML document off the GENI AM API page 251 am_type: XMLRPC string, case insensitive, types in a registry (XML document) linked off the GENI AM API page 252 am_code: XMLRPC integer 253 } 254 }}} 255 256 Integers above are allowed to be negative 257 258 {{{am_type}}} and {{{am_code}}} are optional: AMs need not supply them and clients should not have to use them to understand the nature of the response. 259 They serve to further specify the nature of the return as indicated by {{{geni_code}}} 260 261 Success is indicated by {{{geni_code}}} value of 0 262 263 Error codes and AM types are in an XML document off the GENI AM API page 271 264 272 265 * {{{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. … … 283 276 284 277 GENI standard error codes will be documented on the GENI AM API Wiki page. 285 '''TODO''': The community must standardize on some GENI-wide error codes.286 278 287 279 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. … … 296 288 {{{ 297 289 { 298 code: 0 290 code: { 291 geni_code: 0 292 }, 299 293 value: 300 294 { … … 317 311 {{{ 318 312 { 319 code: 1 313 code: { 314 geni_code: 12 315 } 320 316 value: False 321 317 output: 'No such slice here' 322 318 } 323 319 }}} 324 (That code and output are merely examples. Not in particular that the example codes above use proposal 1 for the return code format.)320 (That code and output are merely examples.) 325 321 326 322 An exception: … … 328 324 GENI AM, but since the version is 2, that is why other function calls will fail with an XMLRPC Fault. 329 325 330 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. 326 ==== Supporting multiple API versions ==== 327 Aggregates are free to support multiple versions of the API. They do so by providing different URLs for each version of the API that they support. 328 Aggregates should have a 'default' URL (the one typically advertised). That version runs whichever version of the API the server chooses (could be the latest, could be something else.) 329 Each server implementing the API must include all methods, including getVersion. 330 331 This change modifies getVersion to include a new required member: 332 geni_api_versions: { 333 1: <URL>, 334 2: <URL>, 335 ... 336 } 337 338 Where the entries indicate versions of the API supported, and URLs are absolute URLs where that version of the API is supported. (As per Change Set B above, this new member is a sub-structure to the {{{value}}} member.) 331 339 332 340 ==== Changes Summary: New Method Signatures ==== … … 338 346 { 339 347 geni_api = 2 340 code = 0 348 code = { 349 geni_code = 0 350 } 341 351 value 342 352 { 343 353 geni_api=2, 344 methodOptions: 345 { 346 <contents of this are TBD, as per above> 347 } 348 <lots of other options follow> 354 geni_api_versions { 355 2: <local URL>, 356 <other versions and URLs as supported> 357 } 358 geni_request_rspec_versions [{ 359 type=GENI 360 version=3 361 schema=... 362 namespace=.... 363 extensions []}, 364 <other version structs>] 365 geni_ad_rspec_versions [{type, version, schema, namespace, extensions},] 349 366 } 350 367 output = <None> … … 354 371 Success Return: 355 372 { 356 code= 0373 code= {geni_code=0} 357 374 value= <GENI v3 Ad or Manifest RSpec string> 358 375 output = <None> … … 366 383 Success Return: 367 384 { 368 code= 0385 code={geni_code=0} 369 386 value= <GENI v3 Manifest RSpec string> 370 387 output = <None> … … 374 391 Success Return: 375 392 { 376 code= 0393 code={geni_code=0} 377 394 value= boolean 378 395 output = <None> … … 382 399 Success Return: 383 400 { 384 code= 0401 code={geni_code=0} 385 402 value= struct (as defined in v1) 386 403 output = <None> … … 392 409 Success Return: 393 410 { 394 code= 0411 code={geni_code=0} 395 412 value= boolean 396 413 output = <None> … … 400 417 Success Return: 401 418 { 402 code= 0419 code={geni_code=0} 403 420 value= boolean 404 421 output = <None>