Changes between Version 24 and Version 25 of GAPI_AM_API_V3


Ignore:
Timestamp:
07/17/12 11:15:34 (7 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • GAPI_AM_API_V3

    v24 v25  
    117117
    118118-----
    119 ''Method Signatures''
     119'''Method Signatures'''
     120
    120121Signatures for the aggregate manager API follow. Examples, return codes, and other details are on the [wiki:GAPI_AM_API_V3_DETAILS Details page]. Most data types and the state machines are explained on the [wiki:GAPI_AM_API_V3/CommonConcepts Common Concepts page].
    121122
     
    218219
    219220 == `Describe` ==
    220 Retrieve a manifest RSpec describing the resources contained by the named entities, e.g. a single slice or a set of the slivers in a slice. This listing and description should be sufficient to allow experimenters to use the resources.
     221Retrieve a manifest RSpec describing the resources contained by the named entities, e.g. a single slice or a set of the slivers in a slice. This listing and description should be sufficiently descriptive to allow experimenters to use the resources.
    221222
    222223{{{
     
    235236}}}
    236237
    237 Note that all options may be omitted by the client, exception `geni_rspec_version` which is required.
     238Note that all options may be omitted by the client except for `geni_rspec_version` which is required.
    238239
    239240For details on the options, see [wiki:GAPI_AM_API_V3_DETAILS#DescribeDetails the Details page].
    240241
    241 This method is part of what `ListResources` used to do, and is similar to ProtoGENI [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#Resolve Resolve].
    242 
    243 Return: On success, the `value` field of the [wiki:GAPI_AM_API_V3/CommonConcepts#ReturnStruct return struct] will contain at struct:
    244 {{{
    245 {
    246    geni_rspec: <geni.rspec, Manifest >
     242This method is part of what `ListResources` used to do in previous versions of the AM API, and is similar to ProtoGENI [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#Resolve `Resolve`].
     243
     244Return: On success, the `value` field of the [wiki:GAPI_AM_API_V3/CommonConcepts#ReturnStruct return struct] will contain a struct:
     245{{{
     246{
     247   geni_rspec: <geni.rspec, a Manifest RSpec>
    247248   geni_urn: <string slice urn of the containing slice>
    248249   geni_slivers: [
     
    250251                  geni_sliver_urn: <string sliver urn>
    251252                  geni_expires: <dateTime.rfc3339 allocation expiration string, as in geni_expires from SliversStatus>,
    252                   geni_allocation_status: <string sliver state - allocated or ?? >,
     253                  geni_allocation_status: <string sliver state - e.g. geni_allocated or geni_provisioned >,
    253254                  geni_operational_status: <string sliver operational state>,
    254255                  geni_error: <optional string, may be omitted entirely, explaining any failure for a sliver>
     
    259260}}}
    260261
    261 Note that the manifest RSpec for allocated slivers may contain less detail than for provisioned slivers. Aggregates are expected to combine the manifests of all requested slivers into a single manifest RSpec. Note that a manifest returned here for only some of the slivers in a slice at this aggregate, may contain references to resources not described in this manifest (they are in other slivers). As a result, such manifests may not be directly usable as a subsequent request.
    262 
    263 If a slice urn is supplied and there are no slivers in the given slice at this aggregate, then `geni_rspec` shall be a valid manifest RSpec, containing 0 `node` or `link` elements - that is, specifying no resources. `geni_slivers` may be an empty array, or may be an array of previous slivers that have since been deleted or expired.
     262Note that the manifest RSpec for allocated slivers may contain less detail than for provisioned slivers. Aggregates are expected to combine the manifests of all requested slivers into a single manifest RSpec. Note that a manifest returned here for only some of the slivers in a slice at this aggregate may contain references to resources not described in this manifest because they are in other slivers.
     263
     264If a slice urn is supplied and there are no slivers in the given slice at this aggregate, then `geni_rspec` shall be a valid manifest RSpec, containing zero (0) `node` or `link` elements - that is, specifying no resources. `geni_slivers` may be an empty array, or may be an array of previous slivers that have since been deleted or expired.
    264265
    265266Manifests are not necessarily static. In general, the manifest of a given sliver should be static once it has reached the operational state `geni_ready` (e.g., fully booted). However, this API does not require that to be true.
     
    280281}}}
    281282
    282 This is the first part of what `CreateSliver` used to do. The second part is now done by `Provision`, and the final part is done by `PerformOperationalAction`.
     283This is the first part of what `CreateSliver` used to do in previous versions of the AM API. The second part is now done by `Provision`, and the final part is done by `PerformOperationalAction`.
    283284
    284285This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#GetTicket GetTicket] operation.
     
    287288{{{
    288289{
    289  geni_rspec: <geni.rspec manifest>,
     290 geni_rspec: <geni.rspec manifest of newly allocated slivers>,
    290291 geni_slivers: [
    291292        {
    292293                  geni_sliver_urn: <string sliver urn>
    293294                  geni_expires: <dateTime.rfc3339 allocation expiration string, as in geni_expires from Status>,
    294                   geni_allocation_status: <string sliver state - allocated or ?? >
     295                  geni_allocation_status: <string sliver state - e.g. geni_allocated>
    295296        },
    296297        ...
     
    299300}}}
    300301
    301 The manifest is a manifest of only newly allocated slivers.
     302The manifest is a manifest RSpec of _only_ newly allocated slivers.
    302303
    303304Arguments: