Changes between Version 1 and Version 2 of DRAFT_GAPI_AM_API_V2


Ignore:
Timestamp:
12/03/11 11:20:47 (12 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • DRAFT_GAPI_AM_API_V2

    v1 v2  
    7171Clients are authorized to take actions at aggregates using [wiki:GeniApiCredentials GENI credentials]. To that end, all methods that require authorization take an argument {{{credentials}}}. In particular, operations on a single GENI slice will require a credential that authorizes the client whose certificate was used to authenticate to operate on the slice named by a {{{slice_urn}}} argument to the method.
    7272
    73 The primary data structure used within this API is a resource specification, known as an RSpec. These XML documents follow a specific set of schemas. They are used by aggregates to list and describe local resources (advertisement RSpecs), by experimenters to describe desired resources (request RSpecs), and then by aggregates to describe reserved resources (manifest RSpecs). For more information on RSpecs, see [wiki:SW_AMAPIV2_Take2_Details#RSpecs the details page].
     73The primary data structure used within this API is a resource specification, known as an RSpec. These XML documents follow a specific set of schemas. They are used by aggregates to list and describe local resources (advertisement RSpecs), by experimenters to describe desired resources (request RSpecs), and then by aggregates to describe reserved resources (manifest RSpecs). For more information on RSpecs, see [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#RSpecs the details page].
    7474
    7575=== Using the GENI AM API ===
    … …  
    162162 * {{{geni_api}}} = '''2''' (Integer current version of this API).
    163163 * List of versions of the API supported by this aggregate. For details on doing this, see [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#SupportingMultipleAPIVersions the Details page].
    164  * List of request RSpec formats supported by this aggregate. For details on RSpecs, see [wiki:SW_AMAPIV2_Take2_Details#RSpecs the Details page].
    165  * List of advertisement RSpec formats supported by this aggregate. For details on RSpecs, see [wiki:SW_AMAPIV2_Take2_Details#RSpecs the Details page].
    166 
    167 For details on !GetVersion arguments, returns, and semantics, and a sample minimal return, see [wiki:SW_AMAPIV2_Take2_Details#GetVersionDetails the Details page].
     164 * List of request RSpec formats supported by this aggregate. For details on RSpecs, see [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#RSpecs the Details page].
     165 * List of advertisement RSpec formats supported by this aggregate. For details on RSpecs, see [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#RSpecs the Details page].
     166
     167For details on !GetVersion arguments, returns, and semantics, and a sample minimal return, see [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#GetVersionDetails the Details page].
    168168
    169169----
    … …  
    193193
    194194==== Arguments Summary ====
    195  *  {{{credentials[]}}}: [wiki:SW_AMAPIV2_Take2_Details#credentialsArgument An array of credentials granting the caller privileges to perform this operation].
    196 
    197  * {{{options}}}: [wiki:SW_AMAPIV2_Take2_Details#Options A NON empty struct with particular semantics described on the Details page].  For this method, options indicate the set of resources that the caller is interested in, or the format of the result. Aggregates should [wiki:SW_AMAPIV2_Take2_Details#DocumentingAggregateAdditions document new options arguments].
    198 
    199 The following members are available for use in the options parameter. All aggregate managers are required to implement these options. See the details page for an explanation of [wiki:SW_AMAPIV2_Take2_Details#Arguments1 the meaning and semantics of each].
     195 *  {{{credentials[]}}}: [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#credentialsArgument An array of credentials granting the caller privileges to perform this operation].
     196
     197 * {{{options}}}: [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#Options A NON empty struct with particular semantics described on the Details page].  For this method, options indicate the set of resources that the caller is interested in, or the format of the result. Aggregates should [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#DocumentingAggregateAdditions document new options arguments].
     198
     199The following members are available for use in the options parameter. All aggregate managers are required to implement these options. See the details page for an explanation of [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#Arguments1 the meaning and semantics of each].
    200200
    201201{{{
    … …  
    215215As with all AM API methods, the return is an XML-RPC struct, whose actual content is in the {{{value}} entry. For !ListResources, {{{value}} is an RSpec listing and describing resources at this aggregate. Depending on the arguments, this may be and advertisement RSpec showing all local resources, or one showing only available local resources, or a manifest RSpec of resources reserved for a particular slice.
    216216
    217 The details page has details on !ListResources arguments, [wiki:SW_AMAPIV2_Take2_Details#Return1 returns], and semantics.
     217The details page has details on !ListResources arguments, [wiki:DRAFT_GAPI_AM_API_V2_Details#Return1 returns], and semantics.
    218218----
    219219=== !CreateSliver ===
    220220
    221 Allocate resources as described in a request RSpec argument to a slice with the named URN. This operation is expected to start the allocated resources asynchronously after the operation has successfully completed. Callers can check on the status of the resources using [wiki:GAPI_AM_API#SliverStatus SliverStatus]. Resources will be reserved until a particular time, set by the aggregate according to policy. That expiration time will be no later than the expiration time of the provided slice credential. This method returns a listing and description of the resources reserved for the slice by this operation, in the form of a manifest RSpec.
     221Allocate resources as described in a request RSpec argument to a slice with the named URN. This operation is expected to start the allocated resources asynchronously after the operation has successfully completed. Callers can check on the status of the resources using [#SliverStatus SliverStatus]. Resources will be reserved until a particular time, set by the aggregate according to policy. That expiration time will be no later than the expiration time of the provided slice credential. This method returns a listing and description of the resources reserved for the slice by this operation, in the form of a manifest RSpec.
    222222
    223223{{{
    … …  
    249249 * {{{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].
    250250
    251  *  {{{credentials[]}}}: [wiki:SW_AMAPIV2_Take2_Details#credentialsArgument An array of credentials granting the caller privileges to perform this operation].
     251 *  {{{credentials[]}}}: [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#credentialsArgument An array of credentials granting the caller privileges to perform this operation].
    252252
    253253 * {{{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}}}.
    … …  
    255255 * {{{users[]}}}: An array of user structs, which contain information about the users that might login to the sliver that the AM needs to know about. This struct has particular required members, documented on [wiki:DRAFT_GAPI_AM_API_V2_DETAILS the V2 details page].
    256256
    257  * {{{options}}}: [wiki:SW_AMAPIV2_Take2_Details#Options An empty struct with particular semantics described on the Details page].  Aggregates should [wiki:SW_AMAPIV2_Take2_Details#DocumentingAggregateAdditions document new options arguments].
     257 * {{{options}}}: [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#Options An empty struct with particular semantics described on the Details page].  Aggregates should [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#DocumentingAggregateAdditions document new options arguments].
    258258
    259259==== Return Summary ====
    … …  
    290290 * {{{slice_urn}}}: The URN of the slice for which all resources will be freed.
    291291
    292  *  {{{credentials[]}}}: [wiki:SW_AMAPIV2_Take2_Details#credentialsArgument An array of credentials granting the caller privileges to perform this operation].
    293 
    294  * {{{options}}}: [wiki:SW_AMAPIV2_Take2_Details#Options An empty struct with particular semantics described on the Details page].  Aggregates should [wiki:SW_AMAPIV2_Take2_Details#DocumentingAggregateAdditions document new options arguments].
     292 *  {{{credentials[]}}}: [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#credentialsArgument An array of credentials granting the caller privileges to perform this operation].
     293
     294 * {{{options}}}: [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#Options An empty struct with particular semantics described on the Details page].  Aggregates should [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#DocumentingAggregateAdditions document new options arguments].
    295295
    296296==== Return Summary ====
    … …  
    328328 * {{{slice_urn}}}: The URN of the slice for which the resource status is desired.
    329329
    330  *  {{{credentials[]}}}: [wiki:SW_AMAPIV2_Take2_Details#credentialsArgument An array of credentials granting the caller privileges to perform this operation].
    331 
    332  * {{{options}}}: [wiki:SW_AMAPIV2_Take2_Details#Options An empty struct with particular semantics described on the Details page].  Aggregates should [wiki:SW_AMAPIV2_Take2_Details#DocumentingAggregateAdditions document new options arguments].
     330 *  {{{credentials[]}}}: [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#credentialsArgument An array of credentials granting the caller privileges to perform this operation].
     331
     332 * {{{options}}}: [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#Options An empty struct with particular semantics described on the Details page].  Aggregates should [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#DocumentingAggregateAdditions document new options arguments].
    333333
    334334==== Return Summary ====
    … …  
    383383 * {{{slice_urn}}}: The URN of the slice for which the resource reservation will be extended.
    384384
    385  *  {{{credentials[]}}}: [wiki:SW_AMAPIV2_Take2_Details#credentialsArgument An array of credentials granting the caller privileges to perform this operation].
     385 *  {{{credentials[]}}}: [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#credentialsArgument An array of credentials granting the caller privileges to perform this operation].
    386386
    387387 * {{{expiration_time}}}: The date-time string in [http://tools.ietf.org/html/rfc3339 RFC 3339] format in UTC when the reservation should be extended until.
    388388
    389  * {{{options}}}: [wiki:SW_AMAPIV2_Take2_Details#Options An empty struct with particular semantics described on the Details page].  Aggregates should [wiki:SW_AMAPIV2_Take2_Details#DocumentingAggregateAdditions document new options arguments].
     389 * {{{options}}}: [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#Options An empty struct with particular semantics described on the Details page].  Aggregates should [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#DocumentingAggregateAdditions document new options arguments].
    390390
    391391==== Return Summary ====
    … …  
    423423 * {{{slice_urn}}}: The URN of the slice for which all resources will be halted.
    424424
    425  *  {{{credentials[]}}}: [wiki:SW_AMAPIV2_Take2_Details#credentialsArgument An array of credentials granting the caller privileges to perform this operation].
    426 
    427  * {{{options}}}: [wiki:SW_AMAPIV2_Take2_Details#Options An empty struct with particular semantics described on the Details page].  Aggregates should [wiki:SW_AMAPIV2_Take2_Details#DocumentingAggregateAdditions document new options arguments].
     425 *  {{{credentials[]}}}: [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#credentialsArgument An array of credentials granting the caller privileges to perform this operation].
     426
     427 * {{{options}}}: [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#Options An empty struct with particular semantics described on the Details page].  Aggregates should [wiki:DRAFT_GAPI_AM_API_V2_DETAILS#DocumentingAggregateAdditions document new options arguments].
    428428
    429429==== Return Summary ====