Changes between Version 44 and Version 45 of GAPI_AM_API_V3


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

--

Legend:

Unmodified
Added
Removed
Modified
  • GAPI_AM_API_V3

    v44 v45  
    265265Note 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.
    266266
    267 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 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. Attempting to `Describe` an unknown sliver shall result in an error (`SEARCHFAILED` `geni_code`). Attempting to `Describe` a previously deleted or expired sliver shall result in an error (e.g. `SEARCHFAILED` or `EXPIRED` or `ERROR`).
     267If 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. Attempting to `Describe` an unknown sliver shall result in an error (`SEARCHFAILED` `geni_code`) (unless `geni_best_effort` is True). Attempting to `Describe` a previously deleted or expired sliver shall result in an error (e.g. `SEARCHFAILED` or `EXPIRED` or `ERROR`) (unless `geni_best_effort` is True).
    268268
    269269Manifests 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.
     
    358358}}}
    359359
    360 Attempting to `Renew` an unknown sliver shall result in an error (`SEARCHFAILED` `geni_code`). Attempting to `Renew` a previously deleted or expired sliver shall result in an error (e.g. `SEARCHFAILED` or `EXPIRED` or `ERROR`) - the aggregate may have forgotten about it entirely. Attempting to `Renew` a slice with no current slivers at this aggregate may return an empty list of slivers, or may return a list of previous slivers that have since been deleted. Note therefore that an empty list is a valid return from this method.
     360Attempting to `Renew` an unknown sliver shall result in an error (`SEARCHFAILED` `geni_code`) (unless `geni_best_effort` is True). Attempting to `Renew` a previously deleted or expired sliver shall result in an error (e.g. `SEARCHFAILED` or `EXPIRED` or `ERROR`) - the aggregate may have forgotten about it entirely (unless `geni_best_effort` is True). Attempting to `Renew` a slice with no current slivers at this aggregate may return an empty list of slivers, or may return a list of previous slivers that have since been deleted. Note therefore that an empty list is a valid return from this method.
    361361
    362362It is legal to attempt to renew a sliver to a sooner expiration time than the sliver was previously due to expire. Not all aggregates will support this however.
     
    451451}}}
    452452
    453 The returned manifest must be in the format specified by the `geni_rspec_version` option. The returned manifest covers only newly provisioned slivers. Use `Describe` to get a manifest of all provisioned slivers. When `geni_best_effort` is true, all requested slivers are returned, but some slivers may have failed (`geni_allocation_status` will remain `geni_allocated`). Check `geni_error` for details.
     453The returned manifest must be in the format specified by the `geni_rspec_version` option. The returned manifest covers only newly provisioned slivers. Use `Describe` to get a manifest of all provisioned slivers. When `geni_best_effort` is true, all requested slivers are returned, but some slivers may have failed (`geni_allocation_status` will remain `geni_allocated`). Check `geni_error` for details. Attempting to `Provision` an unknown or expired sliver when `geni_best_effort` is false shall result in an error (`SEARCHFAILED` or `EXPIRED` or `ERROR` `geni_code`).
    454454{{{
    455455#!comment
     
    538538Note that aggregates may return other information, such as details on sliver contents, etc.
    539539
    540 Attempting to get status for an unknown sliver shall result in an error (`SEARCHFAILED`). Attempting to get status for a previously deleted sliver shall result in an error (e.g. `SEARCHFAILED` or `EXPIRED` or `ERROR`) - the aggregate may have forgotten about the sliver entirely. Attempting to get `Status()` for a slice with no current slivers at this aggregate may return an empty list for `geni_slivers`, or may return a list of previous slivers that have since been deleted.
     540Attempting to get status for an unknown sliver shall result in an error (`SEARCHFAILED`) (unless `geni_best_effort` is true). Attempting to get status for a previously deleted sliver shall result in an error (e.g. `SEARCHFAILED` or `EXPIRED` or `ERROR`) - the aggregate may have forgotten about the sliver entirely (unless `geni_best_effort` is true). Attempting to get `Status()` for a slice with no current slivers at this aggregate may return an empty list for `geni_slivers`, or may return a list of previous slivers that have since been deleted.
    541541
    542542See the Common Concepts page for details on [wiki:GAPI_AM_API_V3/CommonConcepts#SliverAllocationStates allocation] and [wiki:GAPI_AM_API_V3/CommonConcepts#SliverOperationalStates operational states], [wiki:GAPI_AM_API_V3/CommonConcepts#datetimedatatype sliver expiration times], [wiki:GAPI_AM_API_V3/CommonConcepts#urns urns], and [wiki:GAPI_AM_API_V3/CommonConcepts#credentials credentials].
     
    573573}}}
    574574
    575 Note that this method may return an empty list, if no slivers were in the request or in the specified slice.
     575Note that this method may return an empty list, if no slivers were in the request or in the specified slice. Calling this method on a specific sliver that is unknown, expired, or deleted shall result in an error (`SEARCHFAILED` or `EXPIRED` or `ERROR`), unless `geni_best_effort` is true.
    576576
    577577The optional `geni_resource_status` field MAY be returned for each sliver which contains a resource-specific status that may be more nuanced than the options for `geni_operational_status`.
     
    588588This operation used to be called `DeleteSliver` in earlier versions of this API. To get the functionality of `DeleteSliver`, call `Delete` with the slice URN.
    589589
    590 This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#DeleteSliver `DeleteSliver`] operation and to [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA]'s `DeleteSlice` operation (sec. 6.2.3).
     590This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#DeleteSliver DeleteSliver] operation and to [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA]'s `DeleteSlice` operation (sec. 6.2.3).
    591591
    592592Options include: {{{geni_best_effort}}}
     
    611611Note that aggregates will automatically delete slivers whose expiration time is reached.
    612612
    613 Attempting to delete an unknown sliver will result in an error (`SEARCHFAILED`). Attempting to delete a previously deleted sliver shall result in an error (e.g. `SEARCHFAILED` or `EXPIRED` or `ERROR`) - the aggregate may have forgotten about it entirely. Attempting to delete a slice with no current slivers at this aggregate may return an empty list of slivers, or may return a list of previous slivers that have since been deleted. Details are aggregate specific.
     613Attempting to delete an unknown sliver will result in an error (`SEARCHFAILED`) (unless `geni_best_effort` is true). Attempting to delete a previously deleted sliver shall result in an error (e.g. `SEARCHFAILED` or `EXPIRED` or `ERROR`) - the aggregate may have forgotten about it entirely (unless `geni_best_effort` is true). Attempting to delete a slice with no current slivers at this aggregate may return an empty list of slivers, or may return a list of previous slivers that have since been deleted. Details are aggregate specific.
    614614
    615615See the Common Concepts page for details on [wiki:GAPI_AM_API_V3/CommonConcepts#SliverAllocationStates allocation] and [wiki:GAPI_AM_API_V3/CommonConcepts#SliverOperationalStates operational states], [wiki:GAPI_AM_API_V3/CommonConcepts#OperationsonIndividualSlivers operations on individual slivers], [wiki:GAPI_AM_API_V3/CommonConcepts#geni_best_effort geni_best_effort], [wiki:GAPI_AM_API_V3/CommonConcepts#datetimedatatype sliver expiration times], [wiki:GAPI_AM_API_V3/CommonConcepts#urns urns], and [wiki:GAPI_AM_API_V3/CommonConcepts#credentials credentials].
     
    622622}}}
    623623
    624 This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#Shutdown `Shutdown`] operation. The [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA] specification does not include this operation.
     624This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#Shutdown Shutdown] operation. The [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA] specification does not include this operation.
    625625
    626626No options are required.