call-describe.adoc

Describe

Retrieve a manifest RSpec describing the resources contained by the named entities, e.g. a single slice or a set of the slivers in a slice. This listing and description should be sufficiently descriptive to allow experimenters to use the resources.

Describe is used to list the resources belonging to a particular reservation. The return is the standard AM API struct, with a value that is a struct that always includes a single manifest RSpec, describing the resources in the set of slivers whose URNs were supplied, or describing the entire single slice whose URN was supplied as an argument.

The manifest RSpec should contain all necessary details about resource identity, configuration, and access information necessary for experimenters to use the resources. As that configuration information may change as the resource becomes operationally :ready, this information may change. Otherwise, the manifest is mostly static.

Additionally, Describe returns basic state and expiration information for all queried slivers. Valid values for :allocation_status and :operational_status are described on the Common Concepts page.

Call Syntax

Describe(string urns[], struct credentials[],
         struct rspec_version, struct options[])

Argument 1: urns

See the urns argument for details.

The :single_allocation return from [GetVersion] advertises whether or not a client may invoke this method on only some of the slivers in a given :allocation_state in a given slice (default is false - the client may operate on only some of the slivers in a given state). See also the Operations On Individual Slivers section.

Argument 2: credentials

The standard authorization argument. See the Credentials section.

Argument 3: rspec_version

See the rspec_version argument for details.

Argument 4: options

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

Option: :compressed

Supported by the server	Mandatory
Included by client	Optional
XML-RPC type	boolean
Default	false

An XML-RPC boolean value indicating whether the caller would like the result to be compressed. If the value is true (1), the returned resource list will be compressed according to RFC 1950. If the value is false (0) or unspecified. Note: compressed or not, the XML-RPC return type of the ListResources value field will always be string

Return Value

XML-RPC type

struct

See the sliver info list return for details.

On success, the value field of the return struct will contain a struct:

XML-RPC type

{
   ":rspec": <string.rspec: a Manifest RSpec (possibly compressed)>
   ":urn": <string: slice urn of the containing slice>
   ":slivers": [
               {
                  ":sliver_urn": <string: sliver urn>
                  ":expires": <string.dateTime.rfc3339: allocation expiration string, as in :expires from SliversStatus>,
                  ":allocation_status": <string: sliver state - e.g. :allocated or :provisioned >,
                  ":operational_status": <string: sliver operational state>,
                  (optional) ":error": <string: explaining any failure for a sliver. The field may be omitted entirely but may not be null/None>
               },
               ...
         ]
}

The manifest :rspec is returned using the string.rspec data type.

Note that the manifest RSpec for allocated slivers may contain less detail than for provisioned slivers. Aggregates are expected to combine the manifests of all requested slivers into a single manifest RSpec. Note that a manifest returned here for only some of the slivers in a slice at this aggregate may contain references to resources not described in this manifest because they are in other slivers.

Expired, deleted and unknown slivers, or slices without valid slivers, will cause this call to return SEARCHFAILED. See the urns argument for more details on this error code and return value. Note that when given a slice URN without slivers, the Describe call must return SEARCHFAILED, but may return a value, which must then contain an empty rspec.

Manifests are not necessarily static. In general, the manifest of a given sliver should be static once it has reached the operational state :ready (e.g., fully booted). However, this API does not require that to be true.

Return Codes and Errors

The Describe call can return the usual error codes: BADARGS, ERROR, SERVERERROR and UNAVAILABLE. See Error Codes for general errors.

Additionally, the Describe call can return the following error codes:

FORBIDDEN	Credential does not grant permission to a slice or sliver specified in the urns argument. Or the slice has been shut down.
BADVERSION	Bad Version of manifest RSpec requested with the rspec_version argument.
UNSUPPORTED	The aggregate does not permit operations on individual slivers in the same slice of this form. TODO what does this exactly mean? Is this so?
EXPIRED	The slice and/or sliver has expired.
SEARCHFAILED	The slice or sliver does not exist at this AM.
BUSY	Slice or sliver is temporarily locked, try again later