Changes between Version 11 and Version 12 of AaronHelsinger/GAPI_AM_API_DRAFT/MethodSignatures


Ignore:
Timestamp:
04/16/12 11:57:44 (9 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • AaronHelsinger/GAPI_AM_API_DRAFT/MethodSignatures

    v11 v12  
    1515 == !GetVersion ==
    1616Query static configuration information about this aggregate manager implementation, such as API and RSpec versions supported.
     17
     18For details on the arguments, return structure, and semantics, see [wiki:GAPI_AM_API_V2_DETAILS#GetVersionDetails the details page].
     19
     20The !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.
     21
    1722{{{
    1823struct GetVersion([optional: struct options])
     
    2126The `options` argument may be omitted entirely by clients.
    2227
    23 Return struct:
    24 {{{
    25 
     28The result is an [http://www.xmlrpc.com/spec XML-RPC] struct with at least the following members:
     29{{{
     30{
     31  int geni_api;
     32  struct code = {
     33       int geni_code;
     34       [optional: string am_type;]
     35       [optional: int am_code;]
     36         }
     37  struct value
    2638      {
    2739        int geni_api;
     
    4860             string geni_version <containing an integer>;
    4961       };
    50     }
    51 }}}
     62      }
     63  string output;
     64}
     65}}}
     66
     67=== Return Summary ===
     68
     69As with all AM API methods, the return is an XML-RPC struct. For !GetVersion, it includes:
     70 * The standard AM API {{{code}}}, {{{value}}}, and {{{output}}} entries. For details, see [wiki:AaronHelsinger/GAPI_AM_API_DRAFT/MethodSignatures/CommonConcepts#ReturnStruct the Common Concepts page]
     71 * {{{geni_api}}}: integer version of this API ('''3'''). Repeated here for backwards compatibility.
     72
     73!GetVersion {{{value}}} required return members:
     74 * {{{geni_api}}} = '''3''' (Integer current version of this API).
     75 * List of versions of the API supported by this aggregate. For details on doing this, see [wiki:AaronHelsinger/GAPI_AM_API_DRAFT/MethodSignatures/CommonConcepts#SupportingMultipleAPIVersions the Common Concepts page].
     76 * List of request RSpec formats supported by this aggregate. For details on RSpecs, see [wiki:AaronHelsinger/GAPI_AM_API_DRAFT/MethodSignatures/CommonConcepts#RSpecs the Common Concepts page].
     77 * List of advertisement RSpec formats supported by this aggregate. For details on RSpecs, see [wiki:AaronHelsinger/GAPI_AM_API_DRAFT/MethodSignatures/CommonConcepts#RSpecs the Common Concepts page]. 
     78 * List of supported credential types and versions. For details, see [wiki:AaronHelsinger/GAPI_AM_API_DRAFT/MethodSignatures/CommonConcepts the Common Concepts page].
     79
     80For details on !GetVersion arguments, returns, and semantics, and a sample minimal return, see [wiki:GAPI_AM_API_V2_DETAILS#GetVersionDetails the Details page].
    5281
    5382 == !ListResources ==
    54 Retrieve RSpecs listing resources at this aggregate, an Advertisement RSpec of available resources.
     83Return a listing and description of available resources at this aggregate. The resource listing and description provides sufficient information for clients to select among available resources. These listings are known as RSpecs.
    5584
    5685{{{
     
    5887}}}
    5988
    60 Where options include:
     89The following members are available for use in the options parameter. All aggregate managers are required to honor these options.:
    6190{{{
    6291{
     
    7099}}}
    71100
    72 Note that all options may be omitted by the client, exception `geni_rspec_version` which is required. The aggregate must honor all supplied options.
    73 
    74 `credentials` is the standard argument defined above.
     101
     102Note that all options may be omitted by the client, exception `geni_rspec_version` which is required.
    75103
    76104Return:
    77105A `geni.rspec` advertisment RSpec.
    78106
     107This 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).
     108
    79109 == Describe ==
    80110AKA !ListResources when supplied a slice URN.
    81111
    82 Retrieve a manifest describing the resources contained by the entities named, e.g. a single slice or a set of the slivers in a slice.
     112Retrieve a manifest RSpec describing the resources contained by the entities named, e.g. a single slice or a set of the slivers in a slice. This listing and description should be sufficient to allow experimenters to use the resources.
    83113{{{
    84114struct Describe(string urns[], struct credentials[], struct options[])
    85115}}}
    86116
    87 Where options include:
     117The following members are available for use in the options parameter. All aggregate managers are required to honor these options.:
    88118{{{
    89119{
     
    96126}}}
    97127
    98 Note that all options may be omitted by the client, exception `geni_rspec_version` which is required. The aggregate must honor all supplied options.
    99 
    100 `credentials` is the standard argument defined elsewhere.
     128Note that all options may be omitted by the client, exception `geni_rspec_version` which is required.
    101129
    102130Note that the manifest RSpec for allocated slivers may contain less detail than for provisioned slivers.
     
    123151 == Allocate ==
    124152AKA !CreateSlivers()
    125 Request resources described by the given request RSpec to be allocated to the given slice. On success, one or more slivers are allocated, containing resources satisfying the request, and assigned to the given slice. The manifest RSpec describing those resources is returned.
     153
     154Allocate resources as described in a request RSpec argument to a slice with the named URN.  On success, one or more slivers are allocated, containing resources satisfying the request, and assigned to the given slice. This method returns a listing and description of the resources reserved for the slice by this operation, in the form of a manifest RSpec.
     155
    126156{{{
    127157struct Allocate(string slice_urn,
     
    131161}}}
    132162
    133 `credentials` is the standard argument defined above.
     163This operation is similar to ProtoGENI's [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2#CreateSliver CreateSliver] operation and to the [http://svn.planet-lab.org/attachment/wiki/WikiStart/sfa.pdf SFA]'s !CreateSlice operation (sec. 6.2.1).
     164
     165 * {{{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].
     166
     167 * {{{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}}}.
    134168
    135169Options include: