Changes between Version 6 and Version 7 of GAPI_AM_API_V3


Ignore:
Timestamp:
05/01/12 10:53:53 (12 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • GAPI_AM_API_V3

    v6 v7  
    115115 == !GetVersion ==
    116116Query static configuration information about this aggregate manager implementation, such as API and RSpec versions supported.
    117 
    118 For details on the arguments, return structure, and semantics, see [wiki:GAPI_AM_API_V3_DETAILS#GetVersionDetails the details page].
    119117
    120118The !GetVersion operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#GetVersion GetVersion] operation. The [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA] specification does not include this operation.
     
    179177 * List of advertisement RSpec formats supported by this aggregate. For details on RSpecs, see [wiki:GAPI_AM_API_V3/CommonConcepts#RSpecs the Common Concepts page]. 
    180178 * List of supported credential types and versions. For details, see [wiki:GAPI_AM_API_V3/CommonConcepts the Common Concepts#credentials page].
    181  * Options on how sliver allocation works. See [wiki:API_AM_API_V3/CommonConcepts#OperationsonIndividualSlivers the Common Concepts page].
     179 * Options on how sliver allocation works. See [wiki:GAPI_AM_API_V3/CommonConcepts#OperationsonIndividualSlivers the Common Concepts page].
    182180
    183181For details on !GetVersion arguments, returns, and semantics, and a sample minimal return, see [wiki:GAPI_AM_API_V3_DETAILS#GetVersionDetails the Details page].
     
    205203
    206204Return:
    207 A `geni.rspec` advertisment RSpec. See the Common Concepts page.
     205A `geni.rspec` advertisment RSpec. For details on RSpecs, see [wiki:GAPI_AM_API_V3/CommonConcepts#RSpecs the Common Concepts page].
    208206
    209207Note that this is only part of what !ListResources did in earlier versions of this API. For the what-is-in-my-slice functionality, see `Describe()`.
     
    211209This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#DiscoverResources DiscoverResources] operation and to the [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA]'s !GetResources operation (sec. 6.2.4).
    212210
    213 For details on the options (which are required), see the Details page.
     211For details on the options (which are required), see [wiki:GAPI_AM_API_V3_DETAILS#ListResourcesDetails the Details page].
    214212
    215213 == Describe ==
     
    235233Note that all options may be omitted by the client, exception `geni_rspec_version` which is required.
    236234
    237 For details on the options, see the Details page.
    238 See the Common Concepts page about the credentials, rspec, and urns arguments.
     235For details on the options, see [wiki:GAPI_AM_API_V3_DETAILS#DescribeDetails the Details page].
    239236
    240237This method is part of what !ListResources used to do, and is similar to ProtoGENI [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#Resolve Resolve].
     
    259256Note 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 (they are in other slivers). As a result, such manifests may not be directly usable as a subsequent request.
    260257
    261 For details on rspecs, allocation states, operational states, and datetime values, see the Common Concepts page. See GeniIdentifiers for details on URN structure.
     258See the Common Concepts page about the [wiki:GAPI_AM_API_V3/CommonConcepts#credentials credentials], [wiki:GAPI_AM_API_V3/CommonConcepts#RSpecdatatype rspec], and [wiki:GAPI_AM_API_V3/CommonConcepts#urns urns] arguments, and also for details on [wiki:GAPI_AM_API_V3/CommonConcepts#SliverAllocationStates allocation states], [wiki:GAPI_AM_API_V3/CommonConcepts#SliverOperationalStates operational states], and [wiki:GAPI_AM_API_V3/CommonConcepts#datetimedatatype datetime values]. See GeniIdentifiers for details on URN structure.
    262259
    263260 == Allocate ==
     
    278275
    279276This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#GetTicket GetTicket] operation.
    280 
    281  * {{{slice_urn}}}: The URN of the slice to which the resources specified in {{{rspec}}} will be allocated. For details on GENI AM API URN identifiers, see the [wiki:GeniApiIdentifiers GENI wiki page].
    282  * {{{rspec}}}: An RSpec matching the [http://www.protogeni.net/trac/protogeni/wiki/RSpec GENI standard] request RSpec [http://www.geni.net/resources/rspec/3/request.xsd schema] containing the resources that the caller is requesting for allocation to the slice specified in {{{slice_urn}}}.  See the Common Concepts page.
    283  * `credentials`: The standard authorization argument. See the Common Concepts page.
    284 
    285 Options include:
    286 {{{
    287 {
    288   [optional geni_end_time: <dateTime.rfc3339: requested expiration of all new slivers, may be ignored by aggregates>]
    289 }
    290 }}}
    291 
    292 See the Common Concepts page for details on `geni_end_time`.
    293277
    294278Return struct:
     
    309293The manifest is a manifest of only newly allocated slivers.
    310294
    311 See the Common Concepts page for details on RSpecs, expiration dateTime, and allocation states.
     295Arguments:
     296 * {{{slice_urn}}}: The URN of the slice to which the resources specified in {{{rspec}}} will be allocated. For details on GENI AM API URN identifiers, see the [wiki:GeniApiIdentifiers GENI wiki page].
     297 * {{{rspec}}}: An RSpec matching the [http://www.protogeni.net/trac/protogeni/wiki/RSpec GENI standard] request RSpec [http://www.geni.net/resources/rspec/3/request.xsd schema] containing the resources that the caller is requesting for allocation to the slice specified in {{{slice_urn}}}.  See [wiki:GAPI_AM_API_V3/CommonConcepts#RSpecdatatype the Common Concepts page].
     298 * `credentials`: The standard authorization argument. See [wiki:GAPI_AM_API_V3/CommonConcepts#credentials the Common Concepts page].
     299
     300Options include:
     301{{{
     302{
     303  [optional geni_end_time: <dateTime.rfc3339: requested expiration of all new slivers, may be ignored by aggregates>]
     304}
     305}}}
     306
     307See the Common Concepts page for details on [wiki:GAPI_AM_API_V3/CommonConcepts#geni_end_time `geni_end_time`], [wiki:GAPI_AM_API_V3/CommonConcepts#RSpecdatatype RSpecs], [wiki:GAPI_AM_API_V3/CommonConcepts#datetimedatatype expiration dateTime], and [wiki:GAPI_AM_API_V3/CommonConcepts#SliverAllocationStates allocation states].
    312308
    313309 == Renew ==
     
    321317}}}
    322318
    323 This operation used to be called !RenewSliver. Use Renew(<slice_urn>) to get the equivalent functionality.
     319This operation used to be called !RenewSliver. Use `Renew(<slice_urn>)` to get the equivalent functionality.
    324320
    325321This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#RenewSlice RenewSlice] operation.
    326322
    327 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 `geni_best_effort` and Operations on Individual Slivers.
    328 
    329 {{{expiration_time}}}: The date-time string in [http://tools.ietf.org/html/rfc3339 RFC 3339] format in UTC when the reservation(s) should be extended until. See the Common Concepts page.
    330 
    331 See the Common Concepts page for details on the `urns[]` and `credentiasl[]` arguments.
     323Options 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].
     324
     325Arguments:
     326{{{expiration_time}}}: The date-time string in [http://tools.ietf.org/html/rfc3339 RFC 3339] format in UTC when the reservation(s) should be extended until. See [wiki:GAPI_AM_API_V3/CommonConcepts#datetimedatatype the Common Concepts page].
     327
     328See the Common Concepts page for details on the [wiki:GAPI_AM_API_V3/CommonConcepts#urns `urns[]`] and [wiki:GAPI_AM_API_V3/CommonConcepts#credentials `credentials[]`] arguments.
    332329
    333330Return value is a list of structs:
     
    403400 - {{{geni_best_effort}}}
    404401 - {{{geni_end_time}}}
    405  - `struct geni_users[]`
     402 - `struct geni_users[]`: Resource login information. See [wiki:GAPI_AM_API_V3/CommonConcepts#geni_users the Common Concepts page].
    406403
    407404See the Common Concepts page for details on each option.
     
    445442 - {{{geni_end_time}}}
    446443 - {{{geni_best_effort}}}
    447  - `struct geni_users[]`
     444 - `struct geni_users[]`: Resource login information. See [wiki:GAPI_AM_API_V3/CommonConcepts#geni_users the Common Concepts page].
    448445
    449446Return struct: