Changes between Version 11 and Version 12 of AaronHelsinger/GAPI_AM_API_DRAFT/MethodSignatures
- Timestamp:
- 04/16/12 11:57:44 (12 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
AaronHelsinger/GAPI_AM_API_DRAFT/MethodSignatures
v11 v12 15 15 == !GetVersion == 16 16 Query static configuration information about this aggregate manager implementation, such as API and RSpec versions supported. 17 18 For details on the arguments, return structure, and semantics, see [wiki:GAPI_AM_API_V2_DETAILS#GetVersionDetails the details page]. 19 20 The !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 17 22 {{{ 18 23 struct GetVersion([optional: struct options]) … … 21 26 The `options` argument may be omitted entirely by clients. 22 27 23 Return struct: 24 {{{ 25 28 The 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 26 38 { 27 39 int geni_api; … … 48 60 string geni_version <containing an integer>; 49 61 }; 50 } 51 }}} 62 } 63 string output; 64 } 65 }}} 66 67 === Return Summary === 68 69 As 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 80 For details on !GetVersion arguments, returns, and semantics, and a sample minimal return, see [wiki:GAPI_AM_API_V2_DETAILS#GetVersionDetails the Details page]. 52 81 53 82 == !ListResources == 54 Ret rieve RSpecs listing resources at this aggregate, an Advertisement RSpec of available resources.83 Return 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. 55 84 56 85 {{{ … … 58 87 }}} 59 88 60 Where options include:89 The following members are available for use in the options parameter. All aggregate managers are required to honor these options.: 61 90 {{{ 62 91 { … … 70 99 }}} 71 100 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 102 Note that all options may be omitted by the client, exception `geni_rspec_version` which is required. 75 103 76 104 Return: 77 105 A `geni.rspec` advertisment RSpec. 78 106 107 This 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 79 109 == Describe == 80 110 AKA !ListResources when supplied a slice URN. 81 111 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.112 Retrieve 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. 83 113 {{{ 84 114 struct Describe(string urns[], struct credentials[], struct options[]) 85 115 }}} 86 116 87 Where options include:117 The following members are available for use in the options parameter. All aggregate managers are required to honor these options.: 88 118 {{{ 89 119 { … … 96 126 }}} 97 127 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. 128 Note that all options may be omitted by the client, exception `geni_rspec_version` which is required. 101 129 102 130 Note that the manifest RSpec for allocated slivers may contain less detail than for provisioned slivers. … … 123 151 == Allocate == 124 152 AKA !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 154 Allocate 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 126 156 {{{ 127 157 struct Allocate(string slice_urn, … … 131 161 }}} 132 162 133 `credentials` is the standard argument defined above. 163 This 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}}}. 134 168 135 169 Options include:
