GetVersion

Query static configuration information about this aggregate manager implementation, such as API and RSpec versions supported.

GetVersion Call Syntax

GetVersion()
#  or
GetVersion(struct options)

Argument 1: options

Supported by the server	Mandatory
Included by client	Optional
XML-RPC type	struct

A struct containing optional arguments, indexed by name. See General Options Argument Section.

Note that in GetVersion, the options argument itself is optional, while it is mandatory for all other calls! This means that the options argument may be omitted entirely by clients. This is the only exception to the general rule at General Options Argument Section. The reason is that this method should be understandable by clients expecting any version of this API. And historical API versions support getVersion without options.

This API does not list any options that need to be supported. However, servers do need to support the options argument itself: they should not treat its presence as an error, and ignore any options in it they do not support.

Return Value

XML-RPC type

struct value
{
  ":api" : <int>,
  ":api_versions" : {
      <string: version name> : <string: absolute URL>,
      ...
  },
  ":request_rspec_versions" : [
     {
       "type" : <string: (case insensitive)>,
       "version" : <string: (case insensitive)>,
       "schema" : <string>,
       "namespace" : <string>,
       "extensions" : [ <string>, ... ]
     },
     ...
  ],
  ":ad_rspec_versions" : [
     {
       "type" : <string: (case insensitive)>,
       "version" : <string: (case insensitive)>,
       "schema" : <string>,
       "namespace" : <string>,
       "extensions" : [ <string>, ... ]
     },
     ...
  ],
  ":credential_types" : [
     {
       "type" : <string: (case insensitive)>,
       "version" : <string: (case insensitive)>,
     },
     ...
  ],
  ":am_code_version" : <string>,
  ":am_type" : [ <string>, ... ],
 (optional) ":single_allocation" : <boolean: default false>,
 (optional) ":allocate" : <string: default: ':single' (case insensitive)>
}

GetVersion returns the standard return struct from all AM API methods (output, value, code). See Return Structure.

However, next to the standard AM API code, value, and output entries, GetVersion adds a geni_api integer version of this API (3) to the return structure. This information is also in the value struct but is repeated here for backwards compatibility with AM API v1 clients.

Note	TODO Is the above still useful for this API, as it is not backward compatible? If so, what number do we fill in (a fake large one)?

GetVersion is intended to provide information about the configuration of this aggregate, helping experimenter tools determine how to communicate with this aggregate. The information returned includes 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 value contains an XML-RPC struct struct, the fields are described below.

:api

Mandatory	true
XML-RPC type	int

An integer indicating the revision of the Aggregate Manager API that an aggregate supports. This page documents version 1 of the API.

:api_versions

Mandatory	true
XML-RPC type

  ":api_versions" : {
       <string: this API version> : <string: Absolute URL of this API version>,
       (optional) <string: other API version> : <string: Absolute URL of other API version>,
       ...
  }

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 are free to support multiple versions of the AM API. They do so by providing different URLs for each version of the API that they support. Aggregates should have a 'default' URL (the one typically advertised). That url runs whichever version of the API the server chooses (could be the latest, could be something else.)

When aggregates start supporting a new version of the API, they should keep running the old version of the API for a suitable transition period.

Aggregates running multiple versions of the API must advertise the URLs and versions of the API supported in :api_versions, which is a struct that has 1 or more entries. Each key indicates a supported version of the API, and the matching value is the absolute URL to the XML-RPC server where that version of the API is supported. There is always at least one entry in this list: The called version itself.

Example

":api_versions" : {
  "1": "http://example.com/aggregate_manager/XML-RPC/geni_am/1.0",
  "2": "http://example.com/aggregate_manager/XML-RPC/geni_am/2.0",
  "3": "http://example.com/aggregate_manager/XML-RPC/geni_am/3.0",
  "faa1": "http://example.com/aggregate_manager/XML-RPC/faa_am/1.0"
}

:am_code_version

Mandatory	false
XML-RPC type	string Legal characters alphanumeric, space, `-` (hyphen), `.`, `:` (colon), `#`, `_` (underscore), `+`, `(`, `)` Regular expression `^[a-zA-Z0-9-\.:#_+]+$`

For monitoring and operations, it is very useful to identify the software version that AMs use. Therefore, aggregates are strongly encouraged to advertise their current software revision using the :am_code_version field, though for security reasons some aggregates may choose not to do so. Aggregate developers are expected to include this option, but site operators may select not to expose it.

:am_type

Mandatory	true
XML-RPC type	array of string Legal characters alphanumeric

This option adds a way for aggregates to identify what kind of aggregate this is, and therefore what aggregate specific options or returns are applicable. Aggregates of aggregates may identify as multiple types. One of these types indicates that this is such an aggregate of aggregates, and other listed types indicate that clients may interact with the aggregate as though it is any of the listed types.

The value is a list of strings, of length at least one. It should generally be a list of length 1. Aggregates of aggregates may list multiple types.

Note

TODO: http://groups.geni.net/geni/wiki/GAPI_AM_API_DRAFT/Adopted#ChangeSetN:AddinformationtoGetVersion also mentions the following (do we add this somehow?):

Values should be one of the defined GENI AM types if applicable, as defined by the AM API http://groups.geni.net/geni/attachment/wiki/GAPI_AM_API_V3/CommonConcepts/geni-am-types.xml (As of this proposal, one of orca, foam, protogeni, sfa, dcn. More GENI AM types may be added in the future.)

:single_allocation

Mandatory	false
XML-RPC type	boolean
Default	false

See the Operations On Individual Slivers section.

:allocate

Mandatory	false
XML-RPC type	string (case insensitive)
Default	:single
Allowed values	:single, :disjoint, :many

See the Operations On Individual Slivers section.

:credential_types

Mandatory	true
XML-RPC type

   ":credential_types" : [
     {
      ":type" : <string: (case insensitive, matching '^[a-zA-Z0-9][a-zA-Z0-9-_\.:]*$')>,
      ":version" : <string: (containing an integer)>,
     },
     ...
   ]

Aggregates advertise the type(s) of credentials they support. See also the related credentials argument. There are restrictions on what characters are allowed in the :type string, they are listed at the credentials argument.

"sfa" slice credentials as defined before AM API version 3 will have type=geni_sfa and version=2.
"sfa" slice credentials as of AM API version 3 will be type=geni_sfa, version=3.

Note: AM API v3 adds requirements on URNs and certificates, as well as credentials. A credential is only geni_sfa version 3 if all contained certificates and URNs are AM API v3 compliant. Experimenters with existing certificates that are not AM API v3 compliant will only get geni_sfa version 2 credentials, unless they first get a new user certificate. As a result, most aggregates should accept both geni_sfa version 3 and version 2 credentials.
ABAC credentials as of AM API version 3 will be type=geni_abac, version=1. These are fully specified here (we use version 1.1 from that page).

For example, an aggregate that accepts ABAC credentials, SFA slice credentials that were issued prior to AM API v3, and SFA slice credentials from AM API version 3, would include this in GetVersion:

Credentials array example

":credential_types" : [
  {
   ":type" : "geni_sfa",
   ":version" " "2"
  },
  {
   ":type" : "geni_sfa",
   ":version" : "3"
  },
  {
   ":type" : "geni_abac",
   ":version" : "1"
  }
]

:request_rspec_versions and :ad_rspec_versions

Mandatory	true
XML-RPC type

  ":*_rspec_versions" : [
     {
       "type" : <string: (case insensitive)>,
       "version" : <string: (case insensitive)>,
       "schema" : <string>,
       "namespace" : <string>,
       "extensions" : [ <string>, ... ]
     },
     ...
  ],

:request_rspec_versions is an array of data structures indicating the RSpec types accepted by this AM in a request. The contract for RSpec versions is described in the Rspec Document. Per that contract, AMs will produce manifest RSpecs with a schema that is based on the given request type and version.

:ad_rspec_versions is an array of data structures indicating what types of RSpec advertisements may be produced by this AM in [ListResources].

The elements used within :request_rspec_versions and :ad_rspec_versions are:

type: A case-insensitive string which together with version comprises the type of RSpec. type is typically one of "geni", "protogeni", "sfa", or "orbit".
version: A case-insensitive string which together with type comprises the type of RSpec. version should be a type-specific version identifier as specified by the appropriate control framework.
schema: A URL pointing to a schema which can be used to verify the given type of RSpec. Required, but may be empty. This is a standard XML schema URL, so the string should follow the applicable standards. See http://www.w3.org/TR/xml-names11/ and http://www.w3.org/TR/xmlschema11-1/
namespace: An XML namespace which the RSpec of the given type belongs to. May be empty. Required, but may be empty. This is a standard XML namespace, so the string should follow the applicable standards. See http://www.w3.org/TR/xml-names11/ and http://www.w3.org/TR/xmlschema11-1/.
extensions: 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. Required, but may be empty.

Return Codes and Errors

See Error Codes for general errors. There are no special cases for the GetVersion call.

Examples

Example Reply

{
  "code" : {
       "geni_code" : 0 # Success
       # am_type and am_code are optional. Leaving them out.
     },
  "value" :
      {
        ":api" : "faa1",
        ":api_versions" : {
             "faa1" : "http://example.com/aggregate_manager/XML-RPC/faa_am/1.0",
             "3" : "http://example.com/aggregate_manager/XML-RPC/geni_am/3.0" #optional but included here
        },
        ":request_rspec_versions" : [{
             "type" : "GENI",
             "version" : "3",
             "schema" : "http://www.geni.net/resources/rspec/3/request.xsd",
             "namespace" : "http://www.geni.net/resources/rspec/3",
             "extensions" : ["http://hpn.east.isi.edu/rspec/ext/stitch/0.1/stitch-schema.xsd"]
        }],
        ":ad_rspec_versions" : [{
             "type" : "GENI",
             "version" : "3",
             "schema" : "http://www.geni.net/resources/rspec/3/ad.xsd",
             "namespace" : "http://www.geni.net/resources/rspec/3",
             "extensions" : ["http://hpn.east.isi.edu/rspec/ext/stitch/0.1/stitch-schema.xsd"]
        }],
        ":credential_types" : [{ # This AM accepts only SFA style credentials for API v3
             ":type" : "geni_sfa",
             ":version" : "3"
       }],
       ":single_allocation" : false, # can operate on individual slivers. This is the default, so could legally be omitted here.
       ":allocate" : "geni_many", # Can do multiple Allocates. This is not the default value, so is required here.
       ":am_code_version" : "c6395734b45abc96d6d2ec703a28b5862ebbc898",
       ":am_type" : [ "protogeni" ]
      },
  "output" : ""
}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

call-getversion.adoc

call-getversion.adoc

GetVersion

Argument 1: options

Return Value

:api

:api_versions

:am_code_version

:am_type

:single_allocation

:allocate

:credential_types

:request_rspec_versions and :ad_rspec_versions

Return Codes and Errors

Examples

Files

call-getversion.adoc

Latest commit

History

call-getversion.adoc

File metadata and controls

GetVersion

Argument 1: options

Return Value

:api

:api_versions

:am_code_version

:am_type

:single_allocation

:allocate

:credential_types

:request_rspec_versions and :ad_rspec_versions

Return Codes and Errors

Examples