Changes between Version 49 and Version 50 of GAPI_AM_API_V3


Ignore:
Timestamp:
01/18/13 10:00:39 (11 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • GAPI_AM_API_V3

    v49 v50  
    220220
    221221 == `Describe` ==
    222 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 sufficiently descriptive to allow experimenters to use the resources. 
     222Retrieve 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.
    223223
    224224{{{
     
    358358}}}
    359359
    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.
     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 (no slivers identified) with no current slivers at this aggregate may return an empty list of slivers, may return a list of previous slivers that have since been deleted, or may
     361even return an error (`SEARCHFAILED` or `EXPIRED`). Note therefore that an empty list is a valid return from this method.
    361362
    362363It 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.
     
    453454}}}
    454455
    455 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. 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`).
     456The 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`).  Attempting to `Provision` a slice (no slivers identified) with no current slivers at this aggregate shall return an error (`SEARCHFAILED`).
     457
    456458{{{
    457459#!comment
    458 FIXME: Provision implicitly only applies to geni_allocated slivers, when invoked with a slice_urn?
    459460 may be `geni_failed` or `geni_unallocated` or
    460461}}}
     
    541542Note that aggregates may return other information, such as details on sliver contents, etc.
    542543
    543 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.
     544Calling `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 (no slivers identified) with no current slivers at this aggregate may return an empty list for `geni_slivers`, may return a list of previous slivers that have since been deleted, or may even return an error (e.g. `SEARCHFAILED` or `EXPIRED`). Note therefore that `geni_slivers` may be an empty list.
    544545
    545546See 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].
     
    576577}}}
    577578
    578 Note 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.
     579Note that `PerformOperationalAction` may return an empty list, if no slivers were in the request or in the specified slice. However, the method may instead return an error (e.g. `SEARCHFAILED`). 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.
    579580
    580581The 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`.
     
    614615Note that aggregates will automatically delete slivers whose expiration time is reached.
    615616
    616 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.
     617Calling `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 (no slivers identified) with no current slivers at this aggregate may return an empty list of slivers, may return a list of previous slivers that have since been deleted, or may even return an error (e.g. `SEARCHFAILED` or `EXPIRED); details are aggregate specific.
    617618
    618619See 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].