Changes between Version 1 and Version 2 of GAPI_AM_API_V3_DETAILS


Ignore:
Timestamp:
04/27/12 16:46:31 (12 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • GAPI_AM_API_V3_DETAILS

    v1 v2  
    1818
    1919''' TBD: What goes here?'''
     20
     21== !GetVersion Details ==
     22
     23Sample output:
     24
     25'''FIXME FIXME'''
     26
     27{{{
     28{
     29  geni_api = 2 # This is AM API v2
     30  code = {
     31       geni_code = 0 # Success
     32       # am_type and am_code are optional. Leaving them out.
     33     }
     34  value =
     35      {
     36        geni_api = 2 # Match above
     37        geni_api_versions = {
     38             2 = <This server's AM API absolute URL>
     39             # optional: 1 = <Some other URL for talking AM API v1 to the same aggregate
     40        }
     41        geni_request_rspec_versions = [{
     42             type = "GENI"
     43             version = "3"
     44             schema = "http://www.geni.net/resources/rspec/3/request.xsd"
     45             namespace = "http://www.geni.net/resources/rspec/3"
     46             extensions = ["http://hpn.east.isi.edu/rspec/ext/stitch/0.1/stitch-schema.xsd", <other URLs here>]
     47        }]
     48        geni_ad_rspec_versions = [{
     49             type = "GENI"
     50             version = "3"
     51             schema = "http://www.geni.net/resources/rspec/3/ad.xsd"
     52             namespace = "http://www.geni.net/resources/rspec/3"
     53             extensions = ["http://hpn.east.isi.edu/rspec/ext/stitch/0.1/stitch-schema.xsd", <other URLs here>]
     54        }]
     55      }
     56  output = <None>
     57}
     58}}}
     59
     60=== Return ===
     61!GetVersion returns the version of the Aggregate Manager API running locally, the RSpec schemas supported, and the URLs where versions of the AM API are running. The return is an XML-RPC struct whose members are described below.
     62
     63 `geni_api`::
     64    An integer indicating the revision of the Aggregate Manager API that an aggregate supports. This page documents version 2 of the API. This value is duplicated here and within the {{{value}}} return struct for backwards compatibility with AM API v1 clients.
     65
     66{{{code}}}, {{{value}}}, and {{{output}}} together provide the [#ReturnStruct standard return from all AM API methods], which has a specific [#ReturnStruct structure and semantics described below], including specifics of the {{{code}}} and {{{output}}} members.
     67
     68  `value`::
     69       For !GetVersion, {{{value}}} is an XML-RPC struct containing the actual return for the method. On success, this is required. Optional (and not defined) on failure or error.
     70
     71==== !GetVersion return codes ====
     72Aggregates shall return consistent values for {{{geni_code}}} as described here. Success is always indicated using a {{{geni_code}}} value of {{{0}}}. On error, return the appropriate GENI error code in {{{geni_code}}}, as listed in this table. These error codes are part of a [#ReturnStruct larger set of codes with specific meanings required by this API, described below].
     73
     74|| '''''Error''''' || '''''Condition''''' ||
     75|| `ERROR`         || Internal error ||
     76|| `SERVERERROR`   || Server error ||
     77
     78 `geni_api`::
     79    An integer indicating the revision of the Aggregate Manager API that an aggregate supports. This page documents version 2 of the API.
     80
     81 `geni_api_versions`::
     82    An XML-RPC struct indicating the versions of the Aggregate Manager API supported at this aggregate, and the URLs at which those API versions can be contacted. This element is required, and shall include at least 1 entry indicating the local aggregate manager URL and the version of the API supported at that URL. Aggregates supporting multiple versions of the Aggregate Manager API should [#SupportingMultipleAPIVersions conform to the guidelines specified below].
     83{{{
     84geni_api_versions: an XML-RPC struct containing 1+ entries of:
     85  Name: Integer - supported GENI AM API version
     86  Value: String - Absolute URL to the XML-RPC server implementing that version of the GENI AM API
     87}}}
     88
     89 `geni_request_rspec_versions`::
     90    An array of data structures indicating the RSpec types accepted by this AM in a request. The [#RSpecs contract for RSpec versions is described with links to further reading below].
     91
     92 `geni_ad_rspec_versions`::
     93    An array of data structures indicating what types of RSpec advertisements may be produced by this AM in !ListResources.
     94
     95{{{geni_request_rspec_versions}}} and {{{geni_ad_rspec_versions}}} refer to the RSpec formats supported at this aggregate. The [#RSpecs contract for RSpec versions is described with links to further reading below].
     96 
     97
     98Elements used within {{{geni_request_rspec_versions}}} and {{{geni_ad_rspec_versions}}}:
     99 `type`, `version`::
     100   Two ''case-insensitive'' strings which together comprise the type of RSpec. The RSpec `type` should be one of "geni", "protogeni", "sfa", "orca", "openflow", or "orbit". `version` should be a type-specific version identifier as specified by the appropriate control framework. The "geni" type is reserved for GENI standard format RSpecs, following the schemas hosted at http://www.geni.net/resources/rspec.
     101
     102 `schema`::
     103   An optional URL pointing to a schema which can be used to verify the given type of RSpec.
     104
     105 `namespace`::
     106   An optional XML namespace which the RSpec of the given type belongs to.
     107
     108 `extensions`::
     109   An array of aggregate-specific strings denoting which extensions are supported. In the case of GENI standard RSpecs, these are XML namespaces which denote the extension as a whole.
     110
     111-----
     112== !ListResources Details ==
     113 `geni_available`::
     114    Optional. An [http://www.xmlrpc.com/spec XML-RPC] boolean value indicating whether the caller is interested in all resources or available resources. If this value is {{{true}}}, the result should contain only available resources. If this value is {{{false}}} or unspecified, both available and allocated resources should be returned. The Aggregate Manager is free to limit visibility of certain resources based on the {{{credentials}}} parameter.
     115
     116 `geni_compressed`::
     117    Optional. An [http://www.xmlrpc.com/spec XML-RPC] boolean value indicating whether the caller would like the result to be compressed. If the value is {{{true}}}, the returned resource list will be compressed according to [http://www.ietf.org/rfc/rfc1950.txt RFC 1950]. If the value is {{{false}}} or unspecified, the return will be text.
     118
     119 `geni_rspec_version`::
     120    Required. An [http://www.xmlrpc.com/spec XML-RPC] struct indicating the type and version of Advertisement or Manifest RSpec to return. The struct contains 2 members, {{{type}}} and {{{version}}}. {{{type}}} and {{{version}}} are ''case-insensitive'' strings, matching those in {{{geni_ad_rspec_versions}}} as returned by !GetVersion at this aggregate. This option is ''required'', and aggregates are expected to return a {{{geni_code}}} of {{{1}}} ('Bad Arguments') if it is missing. Aggregates should return a {{{geni_code}}} of {{{4}}} ({{{BADVERSION}}}) if the requested RSpec version is not one advertised in !GetVersion as supported. The [#RSpecs contract for RSpec versions is described with links to further reading below].
     121
     122
     123=== Return ===
     124!ListResources returns an RSpec listing and describing resources at this aggregate. Depending on the arguments, this may be all local resources, only available local resources, or a manifest of resources reserved for a particular slice.
     125
     126!ListResources returns the [#ReturnStruct standard return from all AM API methods], which has a specific [#ReturnStruct structure and semantics described below], including specific requirements for the {{{code}}} and {{{output}}} members.
     127
     128
     129  `value`::
     130     !ListResources returns an RSpec in GENI standard schema.
     131
     132
     133    If the aggregate cannot support the requested {{{type}}}/{{{version}}} (that pair is not listed in {{{geni_ad_rspec_versions}}}), then the aggregate returns an error ({{{geni_code}}}) of {{{4}}} ({{{BADVERSION}}}), and the {{{value}}} is not defined.
     134
     135==== !ListResources return codes ====
     136On error, return the appropriate GENI error code in {{{geni_code}}}, as listed in this table. These error codes are part of a [#ReturnStruct larger set of codes with specific meanings required by this API, described below].
     137
     138|| '''''Error''''' || '''''Condition''''' ||
     139|| `BADARGS`       || One of the required arguments is badly formed or missing ||
     140|| `FORBIDDEN`     || Credential does not grant permission to aggregate ||
     141|| `ERROR`         || Internal error ||
     142|| `SERVERERROR`   || Server error ||
     143|| `UNAVAILABLE`   || Unavailable (eg server in lockdown) ||
     144|| `BADVERSION`    || Bad Version of RSpec requested ||
     145
     146-----
     147== Describe Details ==
     148|| '''''Error''''' || '''''Condition''''' ||
     149|| `BADARGS`       || One of the required arguments is badly formed or missing ||
     150|| `FORBIDDEN`     || Credential does not grant permission to the slice ||
     151|| `FORBIDDEN`     || Slice has been shutdown by the Clearinghouse ||
     152|| `BUSY`          || Slice is temporarily locked, try again later ||
     153|| `ERROR`         || Internal error ||
     154|| `SERVERERROR`   || Server error ||
     155|| `UNAVAILABLE`   || Unavailable (eg server in lockdown) ||
     156|| `EXPIRED`       || Slice expired ||
     157|| `BADVERSION`    || Bad Version of RSpec requested ||
     158
     159== Allocate Details ==
     160 `rspec`::
     161    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}}}. These are expected to be consistent with the resources returned by a previous invocation of [wiki:GAPI_AM_API_V3#ListResources ListResources]. If this RSpec is in a format not listed as supported by !GetVersion, then the aggregate will return an error of {{{BADVERSION}}} ({{{4}}}).
     162
     163FIXME: These same errors for Provision?
     164
     165|| '''''Error''''' || '''''Condition''''' ||
     166|| `BADARGS`       || One of the required arguments is missing or badly formed ||
     167|| `FORBIDDEN`     || Credential does not grant permission to the slice ||
     168|| `FORBIDDEN`     || Slice has been shutdown by the Clearinghouse ||
     169|| `UNAVAILABLE`   || AM is temporarily not allowing external users to create slices ||
     170|| `ERROR`         || Internal error ||
     171|| `SERVERERROR`   || Server error ||
     172|| `BADVERSION`    || Bad Version of RSpec requested ||
     173
     174== Renew Details ==
     175
     176|| '''''Error''''' || '''''Condition''''' ||
     177|| `BADARGS`       || One of the required arguments is badly formed or missing ||
     178|| `SEARCHFAILED`  || Slice does not exist at this AM ||
     179|| `FORBIDDEN`     || Credential does not grant permission to the slice ||
     180|| `FORBIDDEN`     || Slice has been shutdown by the Clearinghouse ||
     181|| `BUSY`          || Slice is temporarily locked, try again later ||
     182|| `ERROR`         || Internal error ||
     183|| `SERVERERROR`   || Server error ||
     184|| `EXPIRED`       || Resources already expired ||
     185
     186== Provision Details ==
     187
     188== Status Details ==
     189|| '''''Error''''' || '''''Condition''''' ||
     190|| `BADARGS`       || One of the required arguments is badly formed or missing ||
     191|| `SEARCHFAILED`  || Slice does not exist at this AM ||
     192|| `FORBIDDEN`     || Credential does not grant permission to the slice ||
     193|| `BUSY`          || Slice is temporarily locked, try again later ||
     194|| `ERROR`         || Internal error ||
     195|| `SERVERERROR`   || Server error ||
     196|| `UNAVAILABLE`   || Unavailable (eg server in lockdown) ||
     197|| `EXPIRED`       || Slivers expired ||
     198
     199
     200 `geni_error`::
     201    A free form string. The aggregate manager should set this to a string that could be presented to a researcher to give more detailed information about the state of the resource if its status is {{{failed}}}.
     202
     203== !PerformOperationalAction Details ==
     204
     205== Delete Details ==
     206|| '''''Error''''' || '''''Condition''''' ||
     207|| `BADARGS`       || One of the required arguments is badly formed or missing ||
     208|| `SEARCHFAILED`  || Slice does not exist at this AM ||
     209|| `FORBIDDEN`     || Credential does not grant permission to the slice ||
     210|| `BUSY`          || Slice is temporarily locked, try again later ||
     211|| `ERROR`         || Internal error ||
     212|| `SERVERERROR`   || Server error ||
     213|| `EXPIRED`       || Sliver(s) already expired and gone ||
     214
     215
     216== Shutdown Details ==
     217|| '''''Error''''' || '''''Condition''''' ||
     218|| `BADARGS`       || One of the required arguments is badly formed or missing ||
     219|| `SEARCHFAILED`  || Slice does not exist at this AM ||
     220|| `FORBIDDEN`     || Credential does not grant permission to the slice ||
     221|| `ERROR`         || Internal error ||
     222|| `SERVERERROR`   || Server error ||
     223|| `EXPIRED`       || Slice expired ||
     224|| `INPROGRESS`    || Shutdown in progress ||
     225
     226Note: Aggregates should not return {{{BUSY}}}: this is a time critical operation that should succeed if possible.