call-listresources.adoc

ListResources

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 advertisement RSpecs.

ListResources Call Syntax

ListResources(array credentials, struct rspec_version, struct options)

Argument 1: credentials

The standard authorization argument. See the Credentials section.

When using SFA style credentials, this list must include a valid user credential, granting rights to the caller of the method.

Note	Wim Van de Meerssche: Are slice credentials allowed or disallowed as authorization for ListResources? Or is it always policy of the testbed, with minimum allowed being a user credential of a user at a trusted root.

Argument 2: rspec_version

See the rspec_version argument for details.

Argument 3: options

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

Option: :available

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

An XML-RPC boolean value indicating whether the caller is interested in all resources or available resources. If this value is true (1), the result should contain only available resources. If this value is false (0) 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.

Option: :compressed

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

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: Advertisement RSpec

XML-RPC type	string
String content type	string.rspec

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

The value contains an XML-RPC string containing an Advertisement RSpec, or an XML-RPC string containing a compressed RSpec (see :compressed option). The returned advertisement RSpec lists and describes resources at this aggregate. Depending on the arguments, these may be all local resources, or only available local resources.

Return Codes and Errors

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

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

FORBIDDEN	Credential does not grant permission to list resources on this aggregate
BADVERSION	Bad Version of Advertisement RSpec requested

Examples

Example Request

[
   [
      {
      ":type": "geni_sfa",
      ":version": "3",
      ":value": "<?xml version="1.0" encoding="UTF-8" standalone="no"?>
             <signed-credential ...  (Actual credential ommited)
             </signed-credential>"
      }
   ],
   {
   ":available": true,
   ":rspec_version": {
          "version": "3",
          "type": "geni"
          },
   ":compressed": false
   }
]
-----------------

.Example Reply
[source]
------------------
{
"output": "",
"code": {
             ":code": 0
        },
"value": "<?xml version="1.0" encoding="UTF-8"?>
              <rspec xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                     xmlns="http://www.geni.net/resources/rspec/3"
                     xsi:schemaLocation="http://www.geni.net/resources/rspec/3 http://www.geni.net/resources/rspec/3/ad.xsd "
                     type="advertisement"
                     expires="2014-03-17T14:53:37Z" >
                    ... (actual RSpec ommited)
          </rspec>"
}
------------------