Changes between Version 34 and Version 35 of AaronHelsinger/GAPI_AM_API_DRAFT


Ignore:
Timestamp:
03/30/12 10:46:19 (7 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • AaronHelsinger/GAPI_AM_API_DRAFT

    v34 v35  
    955955}}}
    956956
     957At least one credential must be a valid slice credential for the slice specified in `slice_urn` if that is an argument, or for the slice that contains the named slivers, if sliver urns are an argument, or a valid administrative credential with sufficient privileges. Credentials must be valid (signed by a valid GENI certificate authority either directly or by chain, not expired, and grant privileges to the client identified by the SSL client certificate). Each method requires specific privileges, which must be granted by the provided credentials. Note that the semantics of this argument is not clear: most implementations require a single credential to provide all needed privileges. Alternative interpretations might, for example, accumulate privileges from each valid credential to determine overall caller permissions. For details on GENI AM API format credentials, see [wiki:GeniApiCredentials the GENI wiki].
     958
    957959=== `geni_end_time` ===
    958960The `geni_end_time` argument requests an expiration of the specified slivers. It is in dateTime.rfc3339 format (defined above).
     
    980982]
    981983}}}
     984
     985=== `options` ===
     986An XML-RPC struct. For !GetVersion only, this argument is optional. In all other methods, it is required. Only !ListResources has required entries in the options struct. Aggregates are compliant with this API change by accepting this argument. Aggregates may accept entries to this struct. Aggregates should not require any new options to any method - they should always have a reasonable default for any such option. Aggregates should document new `options` arguments. The prefix `geni_` is reserved for members that are part of this API specification. Implementations should choose an appropriate prefix to avoid conflicts.
    982987
    983988 == !GetVersion ==
     
    10421047Note that all options may be omitted by the client, exception `geni_rspec_version` which is required. The aggregate must honor all supplied options.
    10431048
    1044 Where `credentials` is the standard argument defined above.
     1049`credentials` is the standard argument defined above.
    10451050
    10461051Where supplying `geni_sliver_urns`, whether or not the `geni_slice_urn` is also supplied, means return a manifest RSpec showing the (allocated or provisioned) slivers listed - not necessarily the complete slice at this aggregate.
     
    10781083}}}
    10791084
    1080 Where credentials is the standard argument defined above.
     1085`credentials` is the standard argument defined above.
    10811086
    10821087Options include:
     
    11071112AKA !RenewSliver() or !RenewAllocated
    11081113Request that the named slivers be renewed, with their expiration extended. If possible, the aggregate should extend the slivers to the requested expiration time, or to a sooner time if policy limits apply. This method applies to slivers that are `geni_allocated` or to slivers that are `geni_provisioned`, though different policies may apply to slivers in the different states, resulting in much shorter max expiration times for `geni_allocated` slivers.
    1109 {{{
    1110 struct Renew(string urn[],
     1114
     1115This method has two forms: one takes a single slice URN, the other takes a list of one or more sliver URNs, all contained in the same slice. When a slice URN is supplied, the method operates on all slivers contained in that slice at this aggregate. All other arguments and returns are identical.
     1116
     1117Form 1:
     1118{{{
     1119struct Renew(string slice_urn,
    11111120                    struct credentials[],
    11121121                    dateTime.rfc3339 expiration_time,
     
    11141123}}}
    11151124
    1116 Where credentials is the standard argument defined above.
     1125Form 2:
     1126{{{
     1127struct Renew(string sliver_urn[],
     1128                    struct credentials[],
     1129                    dateTime.rfc3339 expiration_time,
     1130                    struct options)
     1131}}}
     1132
     1133`credentials` is the standard argument defined above.
    11171134
    11181135Options include {{{geni_best_effort}}}
     
    11311148}}}
    11321149
    1133 FIXME: Split Renew(slice) from Renew(slivers)
    1134 
    11351150 == !UpdateAllocations ==
    11361151AKA !UpdateAllocated()
     
    11411156#!comment
    11421157
    1143 {{{
    1144 struct UpdateAllocations(string urn[], struct credentials[], geni.rspec rspec,
     1158This method has two forms: one takes a single slice URN, the other takes a list of one or more sliver URNs, all contained in the same slice. When a slice URN is supplied, the method operates on all slivers contained in that slice at this aggregate. All other arguments and returns are identical.
     1159
     1160Form 1:
     1161{{{
     1162struct UpdateAllocations(string slice_urn, struct credentials[], geni.rspec rspec,
    11451163                                struct options)
    11461164}}}
    11471165
    1148 Where credentials is the standard argument defined above.
     1166Form 2:
     1167{{{
     1168struct UpdateAllocations(string sliver_urn[], struct credentials[], geni.rspec rspec,
     1169                                struct options)
     1170}}}
     1171
     1172`credentials` is the standard argument defined above.
    11491173
    11501174Options include:
     
    11691193The manifest is a manifest of only referenced allocated slivers.
    11701194
    1171 FIXME: Split Update(slice) from Update(slivers)
    11721195FIXME: Is this the same method as for updating provisioned slivers?
    11731196}}}
     1197
    11741198 == !ProvisionSlivers ==
    11751199AKA Provision()
    11761200Request that the named `geni_allocated` slivers be made `geni_provisioned`, instantiating or otherwise realizing the resources, such that they have a valid `geni_operational_status` and may possibly be made `geni_ready` for experimenter use.
    1177 {{{
    1178 struct ProvisionSlivers(string urn[], struct credentials[], 
     1201
     1202This method has two forms: one takes a single slice URN, the other takes a list of one or more sliver URNs, all contained in the same slice. When a slice URN is supplied, the method operates on all slivers contained in that slice at this aggregate. All other arguments and returns are identical.
     1203
     1204Form 1:
     1205{{{
     1206struct ProvisionSlivers(string slice_urn, struct credentials[], 
    11791207                                   struct options)
    11801208}}}
    11811209
    1182 Where credentials is the standard argument defined above.
     1210Form 2:
     1211{{{
     1212struct ProvisionSlivers(string sliver_urn[], struct credentials[], 
     1213                                   struct options)
     1214}}}
     1215
     1216`credentials` is the standard argument defined above.
    11831217
    11841218Options include:
     
    12121246#!comment
    12131247
     1248This method has two forms: one takes a single slice URN, the other takes a list of one or more sliver URNs, all contained in the same slice. When a slice URN is supplied, the method operates on all slivers contained in that slice at this aggregate. All other arguments and returns are identical.
     1249
    12141250{{{
    12151251struct UpdateSlivers(string urn[], struct credentials[], geni.rspec rspec,
     
    12501286 == !SliversStatus ==
    12511287Retrieve status information about the named slivers. This should be relatively dynamic data, not descriptive data as returned in the manifest RSpec by !ListResources.
     1288
     1289This method has two forms: one takes a single slice URN, the other takes a list of one or more sliver URNs, all contained in the same slice. When a slice URN is supplied, the method operates on all slivers contained in that slice at this aggregate. All other arguments and returns are identical.
     1290
    12521291{{{
    12531292struct SliversStatus(string urn[], struct credentials[], struct options)
     
    12811320 == !PerformOperationalAction ==
    12821321Perform the named operational action on the named slivers, possibly changing the `geni_operational_status` of the named slivers.
     1322
     1323This method has two forms: one takes a single slice URN, the other takes a list of one or more sliver URNs, all contained in the same slice. When a slice URN is supplied, the method operates on all slivers contained in that slice at this aggregate. All other arguments and returns are identical.
     1324
    12831325{{{
    12841326struct PerformOperationalAction (string urn[], struct credentials[], string action,
     
    13071349 == !DeleteSlivers ==
    13081350Delete the named slivers, making them `geni_unallocated`. Resources are de-provisioned. No further AM API operations may be performed on slivers that have been deleted.
     1351
     1352This method has two forms: one takes a single slice URN, the other takes a list of one or more sliver URNs, all contained in the same slice. When a slice URN is supplied, the method operates on all slivers contained in that slice at this aggregate. All other arguments and returns are identical.
     1353
    13091354{{{
    13101355struct DeleteSlivers(string urn[], struct credentials[], struct options)