In this document:
The following table contains a list of operations that the APS controller can call through APS application endpoints.
Method | Path | Description |
---|---|---|
POST | /{service-id} | Provision a resource |
GET | /{service-id}/{resource-id} | Get resource properties |
PUT | /{service-id}/{resource-id} | Configure a resource |
DELETE | /{service-id}/{resource-id} | Unprovision a resource |
POST | /{service-id}/{resource-id}/{relation} | Link resources |
DELETE | /{service-id}/{resource-id1}/{relation}/{resource-id2} | Unlink resources |
POST|PUT|GET|DELETE | /{service-id}/{resource-id}/{operation-path} | Custom operation |
POST | /{app-service-id}/{resource-id}/upgrade | Update APS application instance |
GET | /{service-id}/$default | Get default properties |
GET | /{service-id}/$schema | Get resource schema |
GET | /{service-id}/$configurations | Get available configurations |
An application is available for the APS controller usually through a single APS application HTTPS REST endpoint. In some cases, more endpoints can be used.
Each application service that is a factory of resources within a specific type is presented as a separate URL. For example, if the APS application base endpoint is https://endpoints.apsdemo.org/app1/, then the service, whose ID defined in metadata is service1, will be available on https://endpoints.apsdemo.org/app1/service1/.
On the interface between the APS controller and APS application endpoint, APS resources are represented as JSON objects described in Type Definition. Generally, an APS resource is presented in the following common format:
{
"aps": { "id": "<id>", "type": "<type>" },
... /* configuration */ ...
... /* links */ ...
}
Resource properties:
Property | Type | Description |
---|---|---|
aps.id | string | Resource unique identifier, UUID |
aps.type | string | APS type ID |
<configuration> | complex type | Resource properties as defined in its APS type |
<link> | relation link | Named link to another resource or other resources |
This is an example of APS resource representation:
{
"aps": {
"type": "http://www.aps-standard.org/infrastructure/virtual-environment/1",
"id": "16004e17-1604-49ee-a842-13c7daf93750"
},
"hostname": "my.host.com",
"name": "myve",
"description": "My cool VE",
"hardware": {
"bandwidth": 1024,
"cpu": {
"number": 1,
"power": 2700
},
"diskspace": 2048,
"memory": 2048
},
"platform": {
"arch": "i386",
"os": {
"name": "Linux",
"version": "centos-6"
}
},
"status": {
"state": "stopped",
"transition": "starting"
},
"sample": {
"aps": {
"link": "strong",
"href": "/aps/2/resources/66f7c299-174b-4508-bc45-fcbf81252ad5"
}
},
"backups": {
"aps": {
"link": "collection",
"href": "/aps/2/resources/66f7c299-174b-4508-bc45-fcbf81252ad5/links?rel=backups"
}
}
}
When provisioning a resource through an endpoint, the APS controller expects the application to meet the following rules:
Request: POST {app endpoint url}/{service-id}
Successful response: application returns HTTP code 200, and, optionally, a body with resource JSON representation.
Error response: error message and HTTP error code, for example, error 500.
Request:
POST https://endpoint.a.isv1.apsdemo.org/endpoint75319/vpses
APS-Controller-URI:https://10.31.86.75:6308/
APS-Identity-ID:9adb598a-4f97-4a28-b502-71f25d3402a3
APS-Instance-ID:74f752fb-6150-44d2-8c98-e987882411e8
APS-Request-Phase:sync
APS-Transaction-ID:15438-39947
Content-length: ...
{
"aps": {
"type": "http://aps-standard.org/samples/offer-counter-user-func-and-link/vps/1.1",
"id": "87504a7e-4617-4379-91ee-6b069009816c",
"status": "aps:provisioning",
"revision": 2,
"modified": "2015-05-25T14:25:57Z",
"package": {
"id": "c6c16a96-18c5-4090-8e99-c76358525571",
"href": "/aps/2/packages/c6c16a96-18c5-4090-8e99-c76358525571"
}
},
"name": "VPS 22",
"description": "new VPS",
"hardware": {
"CPU": {
"number": 2
},
"diskspace": 32,
"memory": 128
}
}
Successful Response (with empty body):
HTTP/1.1 200 OK
Connection:close
Content-Length:2
Content-Type:application/json
If the application returns a JSON object in its response body containing some properties, the APS controller will set the respective resource properties to the values returned by the application.
HTTP/1.1 500 Internal Server Error
Date: Tue, 17 Mar 2015 16:02:39 GMT
Server: Apache/2.2.15 (CentOS)
X-Powered-By: APS PHP Runtime 2.1-283
Cache-Control: no-cache, must-revalidate
Expires: 0
Content-Length: 295
Connection: close
Content-Type: application/json
{
"code": 500,
"type": "Rest::RestException",
"message": "Can't provide VPS: diskspace is exceeded for subscription.",
"details": {
"error": "APS::Util::Exception",
"message": "Can't provide VPS: diskspace is exceeded for subscription."
}
}
In the platform, the retrieve
method is used to retrieve resource usage.
The method returns the requested data.
Request: GET {app endpoint url}/{service-id}/{resource-id}
Successful Response: HTTP code 200 and requested data in JSON format.
Error Response: HTTP error code, for example, error 500, and error message.
Request:
GET https://endpoint.a.isv1.apsdemo.org/endpoint42150/contexts/95715450-ec90-47e8-9b70-9f22cbb3a783
APS-Controller-URI:https://10.31.86.75:6308/
APS-Instance-ID:cd14aaa9-d05c-41fa-9122-505ca4c7d25c
APS-Transaction-ID:28821-6
APS-Version:2.0
Accept: application/json
HTTP/1.1 200 OK
Date: Tue, 17 Mar 2015 15:50:50 GMT
Server: Apache/2.2.15 (CentOS)
X-Powered-By: APS PHP Runtime 2.1-283
Cache-Control: no-cache, must-revalidate
Expires: 0
Content-Length: 1227
Connection: close
Content-Type: application/json
{
"aps": {
"type": "http://aps-standard.org/samples/offer-counter-user2/context/8.0",
"id": "fd3a7c38-7675-4712-9d22-4f56d4e78100"
},
"name": "My Company",
"diskusagetotal": {
"usage": 2334,
"limit": 23424
},
"memoryusagetotal": {
"usage": 34234,
"limit": 23455
},
"PU_HSSmall": {
"usage": 1481
},
"PU_HS_Large21": {
"usage": 40375,
"limit": null
},
"PU_HS_Large211": {
"usage": 1234,
"limit": 200000
},
"cloud": {
"aps": {
"link": "strong",
"href": "/aps/2/resources/ce749c5a-08d6-4298-bdf3-12083a19612d",
"id": "ce749c5a-08d6-4298-bdf3-12083a19612d"
}
},
"account": {
"aps": {
"link": "strong",
"href": "/aps/2/resources/6884b50e-a5b7-4d3b-814d-1b0682a7f2f5",
"id": "6884b50e-a5b7-4d3b-814d-1b0682a7f2f5"
}
},
"subscription": {
"aps": {
"link": "strong",
"href": "/aps/2/resources/642730ee-8fa4-4973-b215-27356cd7f8d3",
"id": "642730ee-8fa4-4973-b215-27356cd7f8d3"
}
},
"vpses": {
"aps": {
"link": "collection",
"href": "/aps/2/resources/fd3a7c38-7675-4712-9d22-4f56d4e78100/vpses"
}
}
}
HTTP/1.1 404 Not Found
Date: Tue, 17 Mar 2015 16:02:39 GMT
Server: Apache/2.2.15 (CentOS)
X-Powered-By: APS PHP Runtime 2.1-283
Cache-Control: no-cache, must-revalidate
Expires: 0
Content-Length: 321
Connection: close
Content-Type: application/json
{
"code": 404,
"type": "Rest::RestException",
"message": "Specified resource `fd3a7c38-7675-4712-9d22-4f56d4e78100` is not found.",
"details": {
"error": "APS::Util::Exception",
"message": "Specified resource `fd3a7c38-7675-4712-9d22-4f56d4e78100` is not found."
}
}
When updating a property through an endpoint, the APS controller expects the application to meet the Configuration Rules. These are the rules for the usual cases:
Request: PUT {endpoint url}/{service-id}/{resource-id}
Successful response: HTTP code 200, and, optionally, JSON representation of the resource.
Error response: HTTP error code, for example error 500, and error message.
Request:
PUT https://endpoint.a.isv1.apsdemo.org/endpoint75319/vpses/87504a7e-4617-4379-91ee-6b069009816c
APS-Controller-URI:https://10.31.86.75:6308/
APS-Identity-ID:9adb598a-4f97-4a28-b502-71f25d3402a3
APS-Instance-ID:74f752fb-6150-44d2-8c98-e987882411e8
APS-Transaction-ID:16976-39995
Content-length: 817
{
"aps":
{
"type": "http://aps-standard.org/samples/offer-counter-user-func-and-link/vps/1.1",
"id": "87504a7e-4617-4379-91ee-6b069009816c",
"status": "aps:ready",
"revision": 4,
"modified": "2015-05-25T14:47:51Z",
"package":
{
"id": "c6c16a96-18c5-4090-8e99-c76358525571",
"href": "/aps/2/packages/c6c16a96-18c5-4090-8e99-c76358525571"
}
},
"description": "test descr",
"hardware":
{
"CPU":
{
"number": 2
},
"diskspace": 32,
"memory": 128
},
"name": "vps new info"
}
Successful response (with body):
HTTP/1.1 200 OK
APS-Controller-URI:https://10.31.86.75:6308/
Content-Type:application/json
Connection:close
Content-Length: 141
{
"aps":
{
"id": "87504a7e-4617-4379-91ee-6b069009816c",
},
"name": "New name"
}
In the above response, the APS controller requested the application to set the name property to “vps new info”, but the application returned another value - “New name”. In its database, the APS controller must set the “name” to “New name”, that is it must agree with the application.
When removing a resource through an endpoint, the APS controller sends the DELETE request and the 204 code in response.
Request: DELETE {endpoint url}/{service-id}/{resource-id}
Successful response: HTTP code 204
Error response: HTTP error code, for example error 500, and error message.
In case of error response, the APS controller will keep the resource in the aps:unprovisining status.
Request:
DELETE https://endpoint.a.isv1.apsdemo.org/endpoint75319/vpses/7ab1be46-a02c-414c-a44a-88b199ba9047
APS-Controller-URI:https://10.28.99.192:6308/
APS-Instance-ID:aa2b33a0-0dcd-42ab-9be4-c598339948bf
APS-Version:2.2.0
APS-Identity-ID:bcabf9fb-6894-49a5-bdb4-d597f28d1ddd
APS-Transaction-ID:11525-5825'
HTTP/1.1 204 No Content
When linking a resource {resource1} with another resource {resource2} the APS controller addresses the POST request to the endpoint of the {resource1} service.
Request: POST {endpoint url}/{service1-id}/{resource1-id}/{relation}. The body contains the JSON representation of {resource2}.
Successful response: HTTP code 200
Error response: HTTP error code, for example error 500, and error message.
Request for linking the context resource (service ID is contexts) with a VPS whose JSON representation is in the message body:
POST /suwizard1p/contexts/24bf448d-86b0-4c73-a9df-cf65655e81f1/vpses
APS-Application-ID:aa2b33a0-0dcd-42ab-9be4-c598339948bf
Host:endpoint.a.isv1.apsdemo.org
APS-Controller-URI:https://10.28.99.192:6308/
APS-Instance-ID:aa2b33a0-0dcd-42ab-9be4-c598339948bf
APS-Version:2.2.0
APS-Identity-ID:bcabf9fb-6894-49a5-bdb4-d597f28d1ddd
APS-Transaction-ID:13975-6185
{
"aps":
{
"type": "http://aps-standard.org/samples/suwizard1p/vps/1.1",
"id": "b26cd680-4cad-4d7d-ad1b-28cdf4000691",
"status": "aps:provisioning",
"revision": 2,
"modified": "2015-08-10T11:07:34Z",
"subscription": "40396157-535d-4d8b-84f3-dd0e8ca05504",
"package":
{
"id": "f19a107e-2cba-403b-bd5c-9b4105411cee",
"href": "/aps/2/packages/f19a107e-2cba-403b-bd5c-9b4105411cee"
}
},
"description": "Description",
"hardware":
{
"CPU":
{
"number": 2
},
"diskspace": 16,
"memory": 512
},
"name": "VPS102",
"platform":
{
"OS":
{
"name": "centos6"
}
},
"state": "Stopped",
"userName": "Kim Kelvin",
"context":
{
"aps":
{
"link": "strong",
"href": "/aps/2/resources/24bf448d-86b0-4c73-a9df-cf65655e81f1",
"id": "24bf448d-86b0-4c73-a9df-cf65655e81f1",
"subscription": "40396157-535d-4d8b-84f3-dd0e8ca05504"
}
}
}
Response:
HTTP/1.1 200 OK
Content-Length:0
Connection:close
Content-Type:text/html
To unlink a resource {resource1} from another resource {resource2} the APS controller addresses the DELETE request to the endpoint of the {resource1} service.
Request: POST {endpoint url}/{service1-id}/{resource1-id}/{relation}/{resource2-id}
Successful response: HTTP code 204
Error response: HTTP error code, for example error 500, and error message.
Request for unlinking an offer resource (service ID is offers) from a VPS:
DELETE /endpoint/offers/1745b633-59f8-428c-9930-e42b11558512/vpses/d27a726e-7c38-43c6-a2d3-c6c9211cfd74
APS-Application-ID:a9ccc96f-6be9-4e2e-baf8-468b2d68b71a
APS-Application-ID:a9ccc96f-6be9-4e2e-baf8-468b2d68b71a
APS-Controller-URI:https://10.28.99.192:6308/
APS-Instance-ID:a9ccc96f-6be9-4e2e-baf8-468b2d68b71a
APS-Version:2.2.0
APS-Identity-ID:8a1cc5b6-b786-4f65-aeb9-ac0d3523c3d1
APS-Transaction-ID:22734-1466
HTTP/1.1 204 No Content
If the APS controller needs to run a custom operation exposed by an application service on /{service-id}, it must send the REST request to /{service-id}/{resource-id}/{operation}. In the REST request, the APS controller must use the verb announced in the declaration of the operation. Respectively, it can be either POST, PUT, GET, or DELETE request.
Request: POST|PUT|GET|DELETE {endpoint url}/{service1-id}/{resource1-id}/{operation}
Successful response: HTTP code 200 and optionally response body if it is declared in the operation.
Error response: HTTP error code, for example error 500, and error message.
A backup application declares an operation that returns a list of passed backup operations:
"getBackupList": {
"verb": "GET",
"path": "/getBackupList",
"response": {
"contentType": null,
"type": "string",
"items": null
}
}
Respectively, a request from the APS controller for the list of backups must look as follows:
GET /vpsbackup/processes/83351d69-6c4d-46f4-9d9f-3a70ab17063a/getBackupList
APS-Controller-URI:https://10.28.99.192:6308/
APS-Instance-ID:a22e7346-4ef8-4e11-936c-cbafd00dc61c
APS-Version:2.2.0
HTTP/1.1 200 OK
[
{
"backup_id":"1",
"bkp_datetime":"2015-08-10 14:18:01",
"type":"F","state":"SUCCESS","size":"50"
},
{
"backup_id":"2",
"bkp_datetime":"2015-08-10 15:18:01",
"type":"I",
"state":"Scheduled",
"size":null
}
]