Changes between Version 42 and Version 43 of GAPI_AM_API_V3/CommonConcepts


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

--

Legend:

Unmodified
Added
Removed
Modified
  • GAPI_AM_API_V3/CommonConcepts

    v42 v43  
    111111   geni_best_effort: <XML-RPC boolean 1/0, default 0>
    112112}}}
    113 If false, the client is requesting that the aggregate either fully satisfy the request, moving all listed slivers to the desired state, or fully fail the request, leaving all slivers in their original state. If the aggregate cannot guarantee all or nothing success or failure given the included slivers and resource types, the aggregate shall fail the request, returning an appropriate error code (`UNSUPPORTED`). If this option is true, then some slivers may transition to the new state, and some not. Experimenters must examine the return closely to know the state of their slivers - such methods will return data about all requested slivers. Aggregates may optionally return `geni_error` for each sliver for which the operation failed, to indicate further details.  Note that `Allocate` is always all-or-nothing.
     113If false, the client is requesting that the aggregate either fully satisfy the request, moving all listed slivers to the desired state, or fully fail the request, leaving all slivers in their original state and returning an appropriate error code. If the aggregate cannot guarantee all or nothing success or failure given the included slivers and resource types, the aggregate shall fail the request, returning an appropriate error code (`UNSUPPORTED`). If this option is true, then some slivers may transition to the new state, and some not. Experimenters must examine the return closely to know the state of their slivers - such methods will return data about all requested slivers. Aggregates may optionally return `geni_error` for each sliver for which the operation failed, to indicate further details.  Note that `Allocate` is always all-or-nothing.
    114114
    115115It is expected that many aggregates will implement one of the following combinations of options:
     
    121121This API defines two kinds of URNs that may be supplied here, slice URNs and sliver URNs (see [wiki:GeniApiIdentifiers the GENI identifiers page]). Some aggregates may understand other URNs, but these are not defined or required here. Aggregates that accept only URNs defined by this API will return an error when given URNs not in one of those forms.
    122122This API requires that aggregates accept either a single slice URN, or 1 or more sliver URNs that all belong to the same slice. Aggregates are not required to accept both a slice URN and sliver URNs, 2 or more slice URNs, or a set of sliver URNs that crosses multiple slices. Some aggregates may choose to accept other such combinations of URNs. Aggregates that accept only arguments defined by this API will return an error when given more than 1 slice URN, a combination of both slice and sliver URNs, or a set of sliver URNs that belong to more than 1 slice.
     123
     124If the `urns[]` list includes a set of sliver URNs, then the AM shall apply the method to all listed slivers. If the operation fails on one or more of the slivers for any reason, then the whole method fails with an appropriate error code, unless `geni_best_effort` is true and supported.
    123125
    124126=== Sliver Allocation States ===
     
    317319=== `geni_best_effort` ===
    318320 {{{geni_best_effort: <XML-RPC boolean 1 or 0, default false (0)>}}}
    319 Clients may omit this option, but aggregates must honor the option if possible. This option modifies the way that the operation applies to all named slivers. By default (`geni_best_effort`=false), the operation must apply equally to all slivers, either succeeding or failing for all. When true, the aggregate may succeed the operation for some slivers, while failing the operation for other slivers.
     321Clients may omit this option, but aggregates must honor the option if possible. This option modifies the way that the operation applies to all named slivers. By default (`geni_best_effort`=false), the operation must apply equally to all slivers, either succeeding or failing for all (returning an appropriate error code). When true, the aggregate may succeed the operation for some slivers, while failing the operation for other slivers (returning a code of `SUCCESS` but then explaining the per-sliver error in the appropriate `geni_error` field for that sliver).
    320322This option applies to `Provision`, `Renew`, `Delete`, and `PerformOperationalAction`. Each of these methods returns a set of statuses for each requested sliver, allowing the AM to report individual results per sliver. This option does not apply to `Allocate`, which is always all or nothing.
    321323