Changes between Version 46 and Version 47 of GAPI_AM_API_V3
- Timestamp:
- 12/11/12 16:14:46 (11 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
GAPI_AM_API_V3
v46 v47 265 265 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 because they are in other slivers. 266 266 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`).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. 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`). 268 268 269 269 Manifests 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. … … 335 335 Options 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]. 336 336 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 slivermay 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.337 When `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. 338 338 339 339 As 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). … … 358 358 }}} 359 359 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.360 Calling `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. 361 361 362 362 It 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. … … 454 454 {{{ 455 455 #!comment 456 FIXME: Provision implicitly only applies to geni_allocated slivers, when invoked with a slice_urn? 456 457 may be `geni_failed` or `geni_unallocated` or 457 458 }}} … … 538 539 Note that aggregates may return other information, such as details on sliver contents, etc. 539 540 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.541 Calling `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. 541 542 542 543 See 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]. … … 556 557 While 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]. 557 558 558 Options include: {{{geni_best_effort}}}. Default is false (action applies to all slivers equally or none ).559 Options 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). 559 560 560 561 Return: On success, the `value` field of the [wiki:GAPI_AM_API_V3/CommonConcepts#ReturnStruct return struct] will contain a list of structs: … … 611 612 Note that aggregates will automatically delete slivers whose expiration time is reached. 612 613 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.614 Calling `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. 614 615 615 616 See 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].