APS controller can operate an application instance, as a resource, through procedures similar to usual procedures with other resources as described in the Resources document.
However, there are also several operations on the applications
collection affecting the whole selected application
instance. Application instances can initiate some operations with their own resources or with resources of other
application instances through that applications
collection.
In this document:
When testing an operation that can be initiated by an application instance, you can use the cURL
utility
installed on the endpoint host. The following example illustrates how to get a list of all application instances on behalf
of an application instance whose instance ID is specified as {instance-id}
:
# curl -E /var/www/html/vpsbasic/config/{instance-id}.pem \
-k https://{apsc-host}:6308/aps/2/applications
The following sections presents the collections of the operations with the APS applications and APS application instances.
The applications
collection allows an application instance to get a list of all APS application instances and
process a specified APS application instance.
Get more details about this collection in the Applications Collection Details section.
Method | Path | Description |
---|---|---|
GET | /aps/2/applications | Get List of Application Instances |
POST | /aps/2/applications | Install Application Instance |
GET | /aps/2/applications/{instance-id} | Get Application Instance Properties |
PUT | /aps/2/applications/{instance-id} | Update Application Instance |
DELETE | /aps/2/applications/{instance-id} | Unprovision Application Instance |
GET | /aps/2/applications/{instance-id}/{service-id}/{resource-id} | Similar to Getting Resource Properties |
POST | /aps/2/applications/{instance-id}/{service-id}/ | Unlike Provisioning Resources, an application requests the APS controller to register a resource that has been created on the application side. |
PUT | /aps/2/applications/{instance-id}/{service-id}/{resource-id} | Unlike Resource Configuration, an application requests the APS controller to update an APS resource to reflect an update of the respective resource on the application side. For example, this way an application can update its counters on its own will. |
DELETE | /aps/2/applications/{instance-id}/{service-id}/{resource-id} | Unlike Unprovisioning Resources, an application requests the APS controller to unregister an APS resource after the respective resource was removed on the application side. |
APS applications can request the APS controller to operate resources in accordance with granted permissions. In the examples provided in the Resources document, the requester is a user, however an application instance can initiate similar operations as well.
After an application is authenticated by its application certificate while
accessing the APS controller, it may use the /aps/2/application
alias to simplify management of its own resources
stored in the APS database. The usage of the alias is identical to the usage of the
/aps/2/applications/{instance-id} collection, where
{instance-id} is the ID of the application instance that sends the request. However, the list of operations in the
application
collection is extended.
Method | Path | Description |
---|---|---|
GET | /aps/2/application | Get List of Application Services |
GET | /aps/2/application/{service-id}/{resource-id} | Get Resource Details |
POST | /aps/2/application/{service-id}/ | Register Resource |
PUT | /aps/2/application/{service-id}/{resource-id} | Update Resource |
DELETE | /aps/2/application/{service-id}/{resource-id} | Unregister Resource |
POST | /aps/2/application/{service-id}/{resource-id}/{link-id}/{related-resource-id} | Link or Relink Resource |
DELETE | /aps/2/application/{service-id}/{resource-id}/{link-id}/{related-resource-id} | Unlink Resource |
Get more details about the application
alias in the Application Alias Details section.
APS controller exposes the applications
collection for the cases when it is necessary to get a list of all
instances of all APS applications deployed on the platform or to create an APS application instance.
Most of operations require the sender to specify the APS application instance whose resources are affected by the operation.
Security rules:
Below are examples of operations in the applications
collection.
To list all visible application instances, a GET request should be sent to /aps/2/applications
:
GET /aps/2/applications
The response from the APS controller contains a list of JSON objects, each representing an application instance
in compliance with the following schema
:
{
"$schema": "http://json-schema.org/draft-03/schema#",
"id": "http://aps-standard.org/type-definition/application-reference#",
"properties": {
"aps": {
"type": "object",
"required": true,
"properties": {
"id": {
"type": "string",
"required": true,
"description": "application instance identifier - UID"
},
"type": {
"type": "string",
"format": "uri",
"description": "application series identifier - URI"
},
"endpoint": {
"type": "string",
"format": "uri",
"description": "endpoint URI"
},
"package": {
"type": "object",
"required": true,
"description": "package definition ",
"properties": {
"href": {
"type": "string",
"required": true,
"description": "relative URI to package definition"
},
"id": {
"type": "string",
"required": true,
"description": "package identifier - UID"
},
"name": {
"type": "string",
"required": true,
"description": "human-readable package name without versions"
},
"version": {
"type": "string",
"required": true,
"description": "package software version"
},
"release": {
"type": "string",
"required": true,
"description": "package software release"
}
}
}
}
},
"<service id>": {
"type": "object",
"required": true,
"title": "Services available in application instace - one element per service",
"properties": {
"name": {
"type": "string",
"description": "human-readable APS service name"
},
"summary": {
"type": "string",
"description": "human-readable APS service summary"
},
"schema": {
"type": "string",
"required": true,
"description": "relative reference on type schema"
},
"aps": {
"type": "object",
"description": "resource descriptor - only for root service",
"properties": {
"type": {
"type": "string",
"format": "uri",
"required": true,
"description": "APS type ID"
},
"id": {
"type": "string",
"required": true,
"description": "resource identifier - UID"
}
}
}
}
}
}
}
The above schema contains an aps
structure and a structure for each service provided by the application.
aps
structure contains general properties of an application instance:id
- APS ID of the application instancetype
- application ID in the URI formatendpoint
- endpoint URL used to reach the application instancepackage
- properties of the package used to install the application instance<service ID>
structure presents properties of an application service.This is a sample response illustrating two application instances installed from two different packages:
HTTP/1.1 200 OK
[
{
"aps":
{
"id": "a153cf3e-5516-4dcb-a7e9-9e4b2832c73d",
"type": "http://event-mgmt.demo.apsdemo.org/vpsclouds",
"endpoint": "https://endpoint.a.isv1.apsdemo.org:443/vpscloud",
"package": {
"id": "5aa54d4c-9600-416a-8f88-911c55eb55e5"
"href": "/aps/2/packages/5aa54d4c-9600-416a-8f88-911c55eb55e5",
"name": "vpsclouds",
"version": "1.0",
"release": "11"
}
},
"cloud": {
"aps": {
"id": "b4b8c1e7-4969-4215-b0fe-b045ad808c08",
"type": "http://event-mgmt.demo.apsdemo.org/vpsclouds/clouds/1.0"
}
}
},
{
"aps":
{
"id": "577f8e31-5c12-430e-b370-d7f5a4d3a8e6",
"type": "http://aps-standard.org/samples/starter",
"endpoint": "https://endpoint.a.isv1.apsdemo.org:443/starter"
"package": {
"id": "9c0744ef-ab22-4364-b604-31d431fa3789",
"href": "/aps/2/packages/9c0744ef-ab22-4364-b604-31d431fa3789",
"name": "starter",
"version": "1.0",
"release": "1"
}
},
"cloud": {
"aps": {
"id": "4ec6c754-57ac-48ef-ab3b-6606c21832f3",
"type": "http://event-mgmt.demo.apsdemo.org/starter/1.0"
}
}
},
...
]
It is possible to add an RQL query to filter application instances.
For example, the implementing()
filter selects application instances based on the type specified in the filter.
To install an application instance, the initiator must address a POST request to /aps/2/applications
.
The following parameters are needed:
Using package ID:
POST /aps/2/applications
{
"aps": {
"package": {
"id": "5aa54d4c-9600-416a-8f88-911c55eb55e5"
},
"endpoint": "https://endpoint.a.isv1.apsdemo.org:443/vpscloud"
}
}
Specify package by its type (application ID in APP-META.xml
):
POST /aps/2/applications
{
"aps": {
"package": {
"type": "http://event-mgmt.demo.apsdemo.org/vpscloud"
},
"endpoint": "https://endpoint.a.isv1.apsdemo.org:443/vpscloud"
}
}
In the two examples above, the optional version and release tags are missed. If they are not specified, the APS controller will select the latest version and release of the application.
Also, it is possibly to supply the root resource configuration in a request, similar to the way used for resource provisioning, for example:
POST /aps/2/applications
{
"aps": {
"package": {
"type": "http://event-mgmt.demo.apsdemo.org/vpsclouds"
},
"endpoint": "https://endpoint.a.isv1.apsdemo.org:443/vpscloud"
},
"cloud": {
"aps": {
"type": "http://event-mgmt.demo.apsdemo.org/vpscloud/cloud/1.0",
"id": "43f5a0ed-ff4d-4c2c-9ab4-e628e7c4f843",
"status": "aps:ready",
"revision": 1,
"modified": "1930-07-23T18:55:44Z"
},
"name": "new cloud instance",
"description": "hyper-cloud"
}
}
Relationship with other resources also can be specified as a part of resource representation. For example, if an
application
instance must be installed in a certain environment, it can request it through the
environment
link:
POST /aps/2/applications
{
"aps": {
"package": {
"type": "http://event-mgmt.demo.apsdemo.org/vpscloud"
}
},
"cloud": {
"aps": {
"type": "http://event-mgmt.demo.apsdemo.org/vpscloud/cloud/1.0"
},
"name": "new cloud instance",
"environment": {
"aps": { "id": "43f5a0ed-ff4d-4c2c-9ab4-e628e7c4f843" }
}
}
}
The APS controller will resolve automatically all not specified required relations, if possible.
In any case, the response contains all information about the package and application instance, as well as the root resource representation:
HTTP/1.1 200 OK
{
"aps":
{
"id": "a153cf3e-5516-4dcb-a7e9-9e4b2832c73d",
"type": "http://event-mgmt.demo.apsdemo.org/vpscloud",
"endpoint": "https://endpoint.a.isv1.apsdemo.org:443/vpscloud",
"package": {
"id": "5aa54d4c-9600-416a-8f88-911c55eb55e5",
"href": "/aps/2/packages/5aa54d4c-9600-416a-8f88-911c55eb55e5",
"name": "vpscloud",
"version": "1.0",
"release": "11"
}
},
"cloud": {
"aps": {
"id": "b4b8c1e7-4969-4215-b0fe-b045ad808c08",
"type": "http://event-mgmt.demo.apsdemo.org/vpscloud/cloud/1.0"
},
"name": "new cloud instance",
"description": "hyper-cloud"
}
}
The access to /aps/2/applications/{instance-id}
with the GET request is used to get a list of application instance
properties.
GET /aps/2/applications/a153cf3e-5516-4dcb-a7e9-9e4b2832c73d
/aps/2/applications/{instance-id}
. Depending on the request body, it is possible to activate one or both of the
following operations:Note
It is impossible to change anything else with this PUT request.
If an APS application endpoint changed its URI, the application can notify the APS controller about it. The same the linked environment resource can do.
To update the application endpoint, the application needs to provide a new endpoint under the aps.endpoint node in the JSON representation, like below:
PUT /aps/2/applications/80a4b75e-58a7-40e4-a148-dff560e5fa4a
Content-Type: application/json; charset=UTF-8
...
{
"aps": {
"endpoint": "http://apps.farm.com/ff7cf61b-7af2-4d1a-ad66-3f7e032086ed"
}
}
Response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
...
Subsequent access to such an APS application endpoint will be through the URIs with the new base path like
http://apps.farm.com/ff7cf61b-7af2-4d1a-ad66-3f7e032086ed/<service-id>/
.
When there is a need to upgrade an APS application instance to a new version of its APS package imported to the APS
controller,
the upgrade operation is initiated through the APS controller by sending an aps.package
node in the request body.
On receiving it, the controller updates some of properties of the provisioned resources and then issues
a POST request with the upgrade
method to the APS application root service.
This makes the application instance perform application specific updates.
Refer to application upgrade for more details regarding the upgrade development and processing.
Simplest case - update to the latest available version. The package node is empty:
PUT /aps/2/applications/a153cf3e-5516-4dcb-a7e9-9e4b2832c73d
{
"aps": {
"package": {}
}
}
Specify the new package version by the package ID:
PUT /aps/2/applications/a153cf3e-5516-4dcb-a7e9-9e4b2832c73d
{
"aps": {
"package": {
"id": "5aa54d4c-9600-416a-8f88-911c55eb55e5"
}
}
}
Also, one can supply just the new package version:
PUT /aps/2/applications/a153cf3e-5516-4dcb-a7e9-9e4b2832c73d
{
"aps": {
"package": {
"version": "2.0",
"release": "11"
}
}
}
In all cases, the response contains all information about the package and application instance, as well as the root resource representation:
HTTP/1.1 200 OK
{
"aps":
{
"id": "a153cf3e-5516-4dcb-a7e9-9e4b2832c73d",
"type": "http://event-mgmt.demo.apsdemo.org/vpscloud",
"endpoint": "https://endpoint.a.isv1.apsdemo.org:443/vpscloud",
"package": {
"id": "5aa54d4c-9600-416a-8f88-911c55eb55e5",
"href": "/aps/2/packages/5aa54d4c-9600-416a-8f88-911c55eb55e5",
"name": "vpscloud",
"version": "1.0",
"release": "11"
}
},
"cloud": {
"aps": {
"id": "b4b8c1e7-4969-4215-b0fe-b045ad808c08",
"type": "http://event-mgmt.demo.apsdemo.org/vpscloud/cloud/1.0"
},
"name": "new cloud instance",
"description": "hyper-cloud"
}
}
This is an example of a request for upgrade that the APS controller sends to an application root service:
POST /wordpress/80a4b75e-58a7-40e4-a148-dff560e5fa4a/upgrade
{
"aps": {
"type": "http://www.odin.com/web/wordpress/2.0",
"id": "80a4b75e-58a7-40e4-a148-dff560e5fa4a",
"package": {
"id": "b6d35786-8a3b-4931-8122-342aa2130320",
"href": "/aps/2/packages/b6d35786-8a3b-4931-8122-342aa2130320"
}
},
"admin_name": "admin",
"admin_email": "admin@example.com",
"title": [
"The test blog title1",
"The test blog title2"],
...
}
Along with the package ID, the APS controller also sends the new configuration of the application root resource.
For more details, refer to Upgrades processed by Application.
In order to unprovision an application instance, a DELETE request must be sent to /aps/2/applications/{instance-id}
:
DELETE /aps/2/applications/a153cf3e-5516-4dcb-a7e9-9e4b2832c73d
Response:
HTTP/1.1 204 No Content
Expected result:
The /aps/2/application
collection contains more operations compared with the aliased
/aps/2/applications/{self-instance-id} collection.
The examples of using this alias are presented below.
An application can request a list of its own services from the APS controller:
GET /aps/2/application
Response:
HTTP/1.1 200 OK
{
"aps":
{
"id": "a153cf3e-5516-4dcb-a7e9-9e4b2832c73d",
"type": "http://aps-standard.org/samples/event-mgmt",
"endpoint": "https://endpoint.a.isv1.apsdemo.org:443/vpscloud"
},
"cloud":
{
"type": "http://aps-standard.org/samples/event-mgmt/cloud/1.0",
"name": "VPS cloud globals",
"summary": "VPS cloud application global service",
"schema": "/aps/2/types/75"
},
"offers":
{
"type": "http://aps-standard.org/samples/event-mgmt/offer/1.0",
"name": "VPS Parameters",
"summary": "Set of VPS parameters",
"schema": "/aps/2/types/78"
},
"contexts":
{
"type": "http://aps-standard.org/samples/event-mgmt/context/1.0",
"name": "VPS Management",
"summary": "VPS management environment",
"schema": "/aps/2/types/76"
},
"vpses":
{
"type": "http://aps-standard.org/samples/event-mgmt/vps/1.0",
"name": "Virtual Private Server",
"summary": "Cloud virtual private server",
"schema": "/aps/2/types/79"
},
"events":
{
"type": "http://aps-standard.org/samples/event-mgmt/event/1.0",
"name": "Event Processing",
"summary": "Processing event notifications",
"schema": "/aps/2/types/77"
}
}
In the above response, the aps
and cloud
sections represent the application instance and the application root
service:
aps.id
- APS application instance IDaps.type
- APS application ID as specified in Metadata Descriptor (APP-META.xml)aps.endpoint
- URL of the APS application base endpointcloud.type
- ID of the APS type that implements the application resource schema and thus is used to
control the APS application instancecloud.name
- Root service namecloud.summary
- Root service summarycloud.schema
- Internal ID of the resource schema (APS type)The other sections represent the application services other than the root service.
An application can request details of a resource managed through a particular service. For this, it sends
a GET request to /aps/2/application/{service-ID}/{resource-ID}
as illustrated in the following example.
GET /aps/2/application/vpses/099a0e75-9427-4ea7-b1f1-331a81ecd57f
The response will be the same as in a case of using GET /aps/2/resource/{id} sent from a UI script.
An application can request the APS controller to register a new resource provisioned by the application.
Therefore, it sends a request to the proper service, that is to /aps/2/application/{service-ID}
and specifies all needed resource properties in the body.
The APS type ID is a mandatory property in the message body.
The following is an example of registering a VPS with a specified name and state:
POST /aps/2/application/vpses
{
"aps":{"type": "http://event-mgmt.demo.apsdemo.org/vpsclouds/vpses/1.0"},
"name":"VPS-444",
"state":"stopped"
}
Response:
HTTP/1.1 200 OK
{
"aps":
{
"type": "http://event-mgmt.demo.apsdemo.org/vpsclouds/vpses/1.0",
"id": "43f5a0ed-ff4d-4c2c-9ab4-e628e7c4f843",
"status": "aps:ready",
"revision": -1243526976,
"modified": "1930-07-23T18:55:44Z",
"package":
{
"id": "d3ad0a6b-69f1-476f-8aba-cfa72c385978",
"href": "/aps/2/packages/d3ad0a6b-69f1-476f-8aba-cfa72c385978"
}
},
"name": "VPS-444",
"state": "stopped",
"context":
{
"aps":
{
"link": "strong",
"href": "/aps/2/resources/9284f8d3-8ad7-4327-948c-22f780a18fa6",
"id": "9284f8d3-8ad7-4327-948c-22f780a18fa6"
}
},
"offer":
{
"aps":
{
"link": "strong",
"href": "/aps/2/resources/01a1ecd0-0911-450a-b0a7-a37daf8129fc",
"id": "01a1ecd0-0911-450a-b0a7-a37daf8129fc"
}
},
"user":
{
"aps":
{
"link": "strong",
"href": "/aps/2/resources/5f4ef5a5-c9e5-44cf-a862-ea421b7c5534",
"id": "5f4ef5a5-c9e5-44cf-a862-ea421b7c5534"
}
}
}
Note
This operation is different from the Provisioning Resources operation started by a UI script. In the case we consider now, the application notifies the APS controller about a new resource. The APS controller will process the request internally, that is without generating any requests to the application endpoint. If needed, the APS controller will create necessary links. If a new link goes to a resource of another application, that application will be notified.
An application can update a resource managed through a particular service. For this, it sends
a PUT request to /aps/2/application/{service-ID}/{resource-ID}
providing the updated properties in the body.
The resource ID is a mandatory property in the body.
The following example illustrates a request for updating the VPS name:
PUT /aps/2/application/vpses/099a0e75-9427-4ea7-b1f1-331a81ecd57f
{
"aps":{"id":"099a0e75-9427-4ea7-b1f1-331a81ecd57f"},
"name":"VPS-333"
}
The response will be the same as in a case of using PUT /aps/2/resources/{id} sent from a UI script.
An application can request the APS controller to change the current status of a resource provisioned by the application. It uses the same previously described operation.
Example of a request:
PUT /aps/2/application/vpses/099a0e75-9427-4ea7-b1f1-331a81ecd57f
{
"aps":{"id":"099a0e75-9427-4ea7-b1f1-331a81ecd57f"
"status": "initializing"
}
}
Similar to the previous operation, an application can notify the APS controller about a deleted resource.
Sample request:
DELETE /aps/2/application/vpses/43f5a0ed-ff4d-4c2c-9ab4-e628e7c4f843
Sample response:
HTTP/1.1 204 No Content
The notification policy is the same as described for the previous operation.
An application instance can require to link or relink its resource to another resource. For example, if a virtual server is based on the silver level configuration and it is necessary to relink it to the gold level, the application can send a request similar to this:
POST /aps/2/application/vpses/c76dcede-1785-42ad-8322-6f48474e9e69/offer/38cfb775-59d2-4f68-be16-07f51913b8a
In the above request:
c76dcede-1785-42ad-8322-6f48474e9e69
offer
38cfb775-59d2-4f68-be16-07f51913b8a
Sample response:
HTTP/1.1 200 OK
{ // JSON representation of the Gold offer }
The other way of the same operation is to send the APS ID of the related resource in the request body, for example:
POST /aps/2/application/vpses/c76dcede-1785-42ad-8322-6f48474e9e69/offer/
{
"aps": {
"id": "38cfb775-59d2-4f68-be16-07f51913b8a",
"backrel": "vpses"
}
}
In the above request, the optional backrel
property is the ID of the backward link.
An application instance can require the APS controller to unlink a resource if the latter has a weak link with another resource.
DELETE /aps/2/application/vpses/c76dcede-1785-42ad-8322-6f48474e9e69/offer/38cfb775-59d2-4f68-be16-07f51913b8a
Sample response:
HTTP/1.1 204 No Content
If an application requires to remove a strong (required) link, the operation will fail and the APS controller will return an error message like this:
HTTP/1.1 500 Internal Server Error
{
"error": "APS::Util::ConstraintException",
"message": "The link 'offer' is mandatory for 'c76dcede-1785-42ad-8322-6f48474e9e69'."
}