Changes between Version 40 and Version 41 of AaronHelsinger/GAPI_AM_API_DRAFT


Ignore:
Timestamp:
04/02/12 13:07:00 (12 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • AaronHelsinger/GAPI_AM_API_DRAFT

    v40 v41  
    929929}}}
    930930
     931Aggregates are expected to combine the manifests of all requested slivers into a single manifest RSpec.
     932
    931933-----
    932934= Changes Not Included =
    … …  
    945947
    946948 - Allow Shutdown on a single sliver or a list of slivers
    947  - Split !ListResources with {{{slice_urn}}} from !ListResources without. !ListResources with {{{slice_urn}}} we call Resolve(slice_urn).
    948949 - Add {{{geni_am_info}}} block to !GetVersion return (name, id, url, location, description, is_proxy, proxy: {(a geni_am_info block)}, proxy_for[] (list of geni_am_info blocks))
    949950 - Allow the update methods to take a generic rspec argument, allowing AMs to accept full or diff RSpecs
    … …  
    985986If 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 a `geni_rspec_version` option containing that `type`/`version`. (`geni_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`).
    986987
    987 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 an Allocate (was !CreateSliver in API v2) 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`.
     988If 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 an Allocate (was !CreateSliver in API v2) 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 Describe call which supplies a valid slice or sliver URN and an `geni_rspec_version` option containing that supported `type`/`version`.
    988989
    989990In this API, such RSpec fields are labeled as type `geni.rspec`.
    … …  
    10771078
    10781079 == !ListResources ==
    1079 Retrieve RSpecs listing resources at this aggregate. Without arguments, retrieve an Advertisement RSpec of available resources. With arguments naming a particular slice and/or slivers, retrieve a Manifest RSpec of resources allocated to the given slivers.
     1080Retrieve RSpecs listing resources at this aggregate, an Advertisement RSpec of available resources. W
    10801081
    10811082{{{
    … …  
    10881089  boolean geni_available <optional>;
    10891090  boolean geni_compressed <optional>;
    1090   string geni_slice_urn <optional>;
    1091   string geni_sliver_urns[] <optional>;
    10921091  struct geni_rspec_version {
    10931092    string type;
    … …  
    11011100`credentials` is the standard argument defined above.
    11021101
    1103 Where supplying `geni_sliver_urns`, whether or not the `geni_slice_urn` is also supplied, means return a manifest RSpec showing the (allocated or provisioned) slivers listed - not necessarily the complete slice at this aggregate.
     1102Return:
     1103A `geni.rspec` advertisment RSpec.
     1104
     1105 == Describe ==
     1106AKA !ListResources when supplied a slice URN.
     1107
     1108Retrieve a manifest describing the resources contained by the entities named, e.g. a single slice or a set of the slivers in a slice.
     1109{{{
     1110struct Describe(string urns[], struct credentials[], struct options[])
     1111}}}
     1112
     1113Where options include:
     1114{{{
     1115{
     1116  boolean geni_compressed <optional>;
     1117  struct geni_rspec_version {
     1118    string type;
     1119    string version;
     1120  };
     1121}
     1122}}}
     1123
     1124Note that all options may be omitted by the client, exception `geni_rspec_version` which is required. The aggregate must honor all supplied options.
     1125
     1126`credentials` is the standard argument defined elsewhere.
    11041127
    11051128Note that the manifest RSpec for allocated slivers may contain less detail than for provisioned slivers.
    … …  
    11081131{{{
    11091132{
    1110    geni_rspec: <geni.rspec, ad or Manifest - may be empty though)>
     1133   geni_rspec: <geni.rspec, Manifest - may be empty though)>
    11111134   geni_urn: <string slice urn, as requested>
    11121135   geni_slivers: [
    … …  
    11221145}}}
    11231146
    1124 FIXME: Include the slivers struct?
    1125 FIXME: Break this into 3 methods: List(), List(slice), List(slivers)
    1126 
     1147Aggregates are expected to combine the manifests of all requested slivers into a single manifest RSpec.
     1148FIXME: Allow multiple manifests? Options to specify only allocated or only provisioned slivers?
    11271149 == Allocate ==
    11281150AKA !CreateSlivers()
    … …  
    13601382}}}
    13611383
    1362  == !Delete ==
     1384 == Delete ==
    13631385AKA !DeleteSliver
    13641386Delete the named slivers, making them `geni_unallocated`. Resources are de-provisioned. No further AM API operations may be performed on slivers that have been deleted.