Changes between Version 46 and Version 47 of GAPI_AM_API_V3


Ignore:
Timestamp:
12/11/12 16:14:46 (11 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • GAPI_AM_API_V3

    v46 v47  
    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. Calling `Describe` on one or more sliver URNs that are unknown, deleted or expired shall result in an error (e.g. `SEARCHFAILED`, `EXPIRED` or `ERROR` `geni_code`).
    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.
     
    335335Options include {{{geni_best_effort}}}, specifying whether the client prefers all included slivers to be renewed or none, or wants a partial success if possible. See the Common Concepts page under [wiki:GAPI_AM_API_V3/CommonConcepts#geni_best_effort geni_best_effort] and [wiki:GAPI_AM_API_V3/CommonConcepts#OperationsonIndividualSlivers Operations on Individual Slivers].
    336336
    337 When `Renew` is called with `geni_best_effort` false, the entire method will fail (return non-zero code) if any requested sliver cannot be renewed to the requested time, and all slivers will keep their original expiration time. When `Renew` is called with `geni_best_effort` true, some sliver may fail to be renewed. In this case, the allocation state and expiration times do not change. `geni_error` may optionally be returned by the aggregate to explain this failure.
     337When `Renew` is called with `geni_best_effort` false, the entire method will fail (return non-zero `geni_code`) if any requested sliver cannot be renewed to the requested time, and all slivers will keep their original expiration time. When `Renew` is called with `geni_best_effort` true, some slivers may fail to be renewed. In this case, the allocation state and expiration times do not change. `geni_error` may optionally be returned by the aggregate to explain this failure.
    338338
    339339As described [wiki:GAPI_AM_API_V3/CommonConcepts#OperationsonIndividualSlivers here], the `geni_single_allocation` return from `GetVersion` advertises whether or not a client may invoke this method on only some of the slivers in a given `geni_allocation_state` in a given slice (default is false - the client may operate on only some of the slivers in a given state).
     
    358358}}}
    359359
    360 Attempting 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.
     360Calling `Renew` on an unknown, deleted or expired sliver (by explicit URN) shall result in an error (e.g. `SEARCHFAILED`, `EXPIRED` or `ERROR` `geni_code`) (unless `geni_best_effort` is true, in which case the method may succeed, but return a `geni_error` for each sliver that failed). 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.
     
    454454{{{
    455455#!comment
     456FIXME: Provision implicitly only applies to geni_allocated slivers, when invoked with a slice_urn?
    456457 may be `geni_failed` or `geni_unallocated` or
    457458}}}
     
    538539Note that aggregates may return other information, such as details on sliver contents, etc.
    539540
    540 Attempting 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.
     541Calling `Status()` on an unknown, deleted or expired sliver (by explicit URN) shall result in an error (e.g. `SEARCHFAILED`, `EXPIRED` or `ERROR`) (unless `geni_best_effort` is true, in which case the method may succeed, but return a `geni_error` for each sliver that failed). 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.
    541542
    542543See 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].
     
    556557While the `action` argument may be aggregate and sliver type specific (none are required for all aggregates and sliver types), this API does define three common actions that AMs should support if possible: `geni_start`, `geni_stop`, and `geni_restart`. Calling `PerformOperationalAction` with the action `geni_start` corresponds to the final part of what `CreateSliver` did in AM API v2. For more information, see the Common Concepts page section on [wiki:GAPI_AM_API_V3/CommonConcepts#SliverOperationalActions operational actions].
    557558
    558 Options include: {{{geni_best_effort}}}. Default is false (action applies to all slivers equally or none).
     559Options include: {{{geni_best_effort}}}. Default is false (action applies to all slivers equally or none; the method returns an error code without changing the operational state if any sliver fails).
    559560
    560561Return: On success, the `value` field of the [wiki:GAPI_AM_API_V3/CommonConcepts#ReturnStruct return struct] will contain a list of structs:
     
    611612Note that aggregates will automatically delete slivers whose expiration time is reached.
    612613
    613 Attempting 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.
     614Calling `Delete()` on an unknown, expired or deleted sliver (by explicit URN) shall result in an error (e.g. `SEARCHFAILED`, `EXPIRED`, or `ERROR`) (unless `geni_best_effort` is true, in which case the method may succeed and return a `geni_error` for each sliver that failed). 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.
    614615
    615616See 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].