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 |
|
POST |
/aps/2/applications |
|
GET |
/aps/2/applications/{instance-id} |
|
PUT |
/aps/2/applications/{instance-id} |
|
DELETE |
/aps/2/applications/{instance-id} |
|
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 |
/aps/2/application/{service-id}/{resource-id} |
|
POST |
/aps/2/application/{service-id}/ |
|
PUT |
/aps/2/application/{service-id}/{resource-id} |
|
DELETE |
/aps/2/application/{service-id}/{resource-id} |
|
POST |
/aps/2/application/{service-id}/{resource-id}/{link-id}/{related-resource-id} |
|
DELETE |
/aps/2/application/{service-id}/{resource-id}/{link-id}/{related-resource-id} |
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:
An APS application instance (with an SSL certificate) has all permissions to its own resources.
Other actors have access to an application instance if they have access to the root resource of the particular instance.
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.
The aps
structure contains general properties of an application instance:
id
- APS ID of the application instance
type
- application ID in the URI format
endpoint
- endpoint URL used to reach the application instance
package
- properties of the package used to install the application instance
A <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:
APS package specified by its ID or by its type.
Application endpoint specified by its URI.
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:To register the application instance on an endpoint, the new endpoint URI is specified.
To upgrade the application instance using a new version of the APS package, the corresponding package is specified.
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.
Warning
Although it is possible to have instances of the same APS application bound to various package versions, the best practice is to have all the instances upgraded to the latest package version. This is caused by the following UI navigation specifics. If the UI navigation engine discovers several packages of the same APS application it will work with the latest version regardless of the APS application instance version. This may cause incompatibility between the UI requests on one hand and the resource model and backend operations on the other hand.
The simplest way is to upgrade an instance to the latest available package version.
The package
node is empty in this case:
PUT /aps/2/applications/a153cf3e-5516-4dcb-a7e9-9e4b2832c73d
{
"aps": {
"package": {}
}
}
You can 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:
All APS resources related to the removed instance must be removed by the APS controller.
APS controller will calculate right order of removal, starting from resources which are not strongly required by other resources.
If some of resources being deleted are strongly required (strong link) by some resources from other applications, the removal request will fail.
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 ID
aps.type
- APS application ID as specified in Metadata Descriptor (APP-META.xml)
aps.endpoint
- URL of the APS application base endpoint
cloud.type
- ID of the APS type that implements the application resource schema and thus is used to
control the APS application instance
cloud.name
- Root service name
cloud.summary
- Root service summary
cloud.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:
Virtual server APS ID is c76dcede-1785-42ad-8322-6f48474e9e69
Link ID is offer
Gold offer APS ID is 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'."
}