Getting Resources

Get operations do not require any communication with application endpoints, since all resource properties are stored in the APS database managed by the APS controller.

Getting a Resource List

Full Resource List

To get all available resources, one issues a GET request to APS controller endpoint /aps/2/resources. In response, the controller will send a list of resources. Each resource is represented as a JSON object with all properties that are allowed in accordance with the security model.

The number of resources returned is indicated by the Content-Range header in accordance with the pagination rules.

Request:

GET /aps/2/resources
Accept: application/json

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Range: items 0-5/100

[
   {
      "aps":
      {
         "type": "http://basic.demo.apsdemo.org/vpsclouds/vpses/1.0",
         "id": "7ab1be46-a02c-414c-a44a-88b199ba9047",
         "status": "aps:ready",
         "revision": 3,
         "modified": "2014-02-18T10:08:26Z"
      },
      "name": "VPS-103",
      "state": "stopped"
      ...
   },
   {
      "aps":
      {
         "type": "http://basic.demo.apsdemo.org/vpsclouds/vpses/1.0",
         "id": "f276742d-9ca2-445f-9727-d84af0da73fd",
         "status": "aps:ready",
         "revision": 3,
         "modified": "2014-02-18T10:16:16Z"
      },
      "name": "VPS-104",
      "state": "stopped"
      ...
   }
]

Note

When getting a resource list this way, the APS controller does not return the links of the resources. You can get links of resources in different ways, for example, by applying the select(<link_name>) filter or by reading a resource by its APS ID as described later.

Filtered Resource List

Several criteria may be used to filter resources in a request. These criteria are to be submitted as query parameters together with a GET request.

Filtering parameters:

Filter operator

Description

implementing(type)

Fetch only resources of the specified type. Specify either the instantiated type or a parent implemented by this type.

with (property,value) pair

Apply a resource requirement expression as a filter. This option has an effect only when a type with a non-empty configuration is specified in the type filter. For more details on filtering expressions and the list of relational operators please refer to the Resource Query Language.

Note

1. Children of array elements of the configuration cannot be used for filtering.

  1. You can use several comma-separated RQL operators.

Examples of filtering queries:

  • Get only resources of the http://basic.demo.apsdemo.org/vpsclouds/vpses type

    GET /aps/2/resources?implementing(http://basic.demo.apsdemo.org/vpsclouds/vpses)
    
  • Get only VPSes of the http://basic.demo.apsdemo.org/vpsclouds/vpses type where CentOS-6 is installed, that is the following property is found: “platform.OS.name,centos6”: “centos6”.

    GET /aps/2/resources?implementing(http://basic.demo.apsdemo.org/vpsclouds/vpses),eq(platform.OS.name,centos6)
    
  • Get all VPSes of the “http://basic.demo.apsdemo.org/vpsclouds/vpses” type where memory is less than 1024 MB, that is search for the “hardware.memory” property.

    GET /aps/2/resources?implementing(http://basic.demo.apsdemo.org/vpsclouds/vpses),lt(hardware.memory,1024)
    
  • Get a list of VPSes along with their links to offers. This requires the use of the select(<relation_name>) filter, where <relation_name> is the name of the respective relation declared in type definition.

    GET /aps/2/resources?implementing(http://aps-standard.org/samples/offer-mgmt/vps/1.0),select(offer)
    
    [
        {
           "aps":
           { ... },
           "offer":
           {
              "aps": { ... },
              "description": "Light weight servers",
              "hardware": { ... },
              "name": "Silver",
              "platform": { ... }
           },
           "hardware":{ ... },
           "platform": { ... },
           "state": "Stopped",
           "name": "VPS-101",
           "description": "Simplest Web server"
        },
        {
           "aps": { ... },
           "offer": {
              "aps": { ... },
              "description": null,
              "hardware": { ... },
              "name": "Gold",
              "platform": { ... }
           },
           "hardware": { ... },
           "platform": { ... },
           "state": "Stopped",
           "name": "VPS-102",
           "description": "Windows Web server"
        }
    ]
    

Ordered Resource List

To retrieve resources by page, the following query parameters may be used.

Parameter

Argument

Description

limit(start,count)

start
count
The starting record number.
The maximum number of records returned. If no limit is specified, the default limit of 1000 resources is applied.

sort(<+|-><property>)

+
-
property
Sorting in ascending order
Sorting in descending order
Order the list by this property

When paging is active, the total number of matching resources is indicated by the total attribute at the resources element in addition to the number of returned resources indicated by the count attribute.

Examples of queries:

  • Return the first 100 resources, no ordering

    GET /aps/2/resources?limit(0,100)
    
  • Select all offers of type http://user-mgmt.demo.apsdemo.org/vpsclouds/offers, order them by memory and then by disk space, and return the first three of them.

    Request:

    GET /aps/2/resources?implementing(http://user-mgmt.demo.apsdemo.org/vpsclouds/offers),sort(+hardware.memory,+hardware.diskspace),limit(0,3)
    

    Response:

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=UTF-8
    Content-Range: items 0-2/3
    
    [
        {
           "aps":
           {
              "type": "http://user-mgmt.demo.apsdemo.org/vpsclouds/offers/1.0",
              "id": "f1aba008-11c5-42c1-96d2-64e90557c482",
              ...
           },
           "hardware":
           {
              "diskspace": 32,
              "memory": 512
           },
           ...
        },
        {
           "aps":
           {
              "type": "http://user-mgmt.demo.apsdemo.org/vpsclouds/offers/1.0",
              "id": "e9d1ddd2-5fc6-4022-832f-b898addd48d6",
              ...
           },
           "hardware":
           {
              "diskspace": 50,
              "memory": 1024
           },
           ...
        },
        {
           "aps":
           {
              "type": "http://user-mgmt.demo.apsdemo.org/vpsclouds/offers/1.0",
              "id": "a54153c1-6bba-45e9-9c36-db82a6c03d0a",
              ...
           },
           "hardware":
           {
              "memory": 2048,
              "diskspace": 64
           },
           ...
        }
    ]
    

Getting Resource Properties

To read all properties of a resource, the REST GET request must be sent to the APS controller addressed to /aps/2/resources/{ID}. The APS controller must return the JSON representation of the resource. The ID in the URL refers to the identifier of the resource being retrieved. In the resource lookup is successful, HTTP 200 is returned with a resource description, as in the example below. If there is an error, an HTTP error code will be returned.

Request:

GET /aps/2/resources/80a4b75e-58a7-40e4-a148-dff560e5fa4a
Accept: application/json

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
...

{
      "aps": {
        "type": "http://www.parallels.com/web/wordpress/1.0",
        "id": "80a4b75e-58a7-40e4-a148-dff560e5fa4a"
      },

      "login": "admin",
      "email": "admin@example.com",
      "title": "The test blog",
      "locale": "en",

     ...

      "environment": {
         "aps": {
           "link": "strong",
           "href": "/aps/2/resources/1203e863-e68f-400c-b06c-f4d15323e160"
         }
     }
}