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.
In this document:
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.
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.
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"
}
]
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
},
...
}
]
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"
}
}
}