Application Instances

The 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 particular operations with their own resources or with resources of other application instances through the applications collection.

Operations

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 in Brief

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 a List of Application Instances
POST	/aps/2/applications	Install Application Instances
GET	/aps/2/applications/{instance-id}	Get Application Instance Properties
PUT	/aps/2/applications/{instance-id}	Update Application Instances
DELETE	/aps/2/applications/{instance-id}	Unprovision Application Instances
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 that the APS controller 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 using its own algorithm.
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 is 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.

The Application Alias in Brief

After an application is authenticated by its application certificate while accessing the APS controller, it can 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 a List of Application Services
GET	/aps/2/application/{service-id}/{resource-id}	Get Resource Details
POST	/aps/2/application/{service-id}/	Register Resources
PUT	/aps/2/application/{service-id}/{resource-id}	Update Resources
DELETE	/aps/2/application/{service-id}/{resource-id}	Unregister Resources
POST	/aps/2/application/{service-id}/{resource-id}/{link-id}/{related-resource-id}	Link or Relink Resources
DELETE	/aps/2/application/{service-id}/{resource-id}/{link-id}/{related-resource-id}	Unlink Resources

Get more details about the application alias in the Application Alias Details section.

Applications Collection Details

The APS controller exposes the applications collection in 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 operations require the sender to specify the APS application instance with resources 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 that instance.

Below are examples of operations in the applications collection.

Get a List of Application Instances

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 URL 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.

Install Application Instances

To install an application instance, the initiator must address a POST request to /aps/2/applications. The following parameters are required:

• The APS package specified by its ID or by its type.

• The Application endpoint specified by its URL.

Using the package ID:

POST /aps/2/applications

{
   "aps": {
        "package": {
            "id": "5aa54d4c-9600-416a-8f88-911c55eb55e5"
         },
         "endpoint": "https://endpoint.a.isv1.apsdemo.org:443/vpscloud"
   }
}

Specify the 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.

It is also possible to supply the root resource configuration in a request similar to the request 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"
   }
}

The relationship with other resources also can be specified as a part of the resource representation.

The APS controller will automatically resolve all not-specified required relations, if possible.

The response always 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"
  }
}

Get Application Instance Properties

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

Update Application Instances

In order to update an application instance, a PUT request must be addressed to

/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 URL 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.

Change an Application Instance Endpoint

If an APS application endpoint changed its URL, the application can notify the APS controller about it.

To update its endpoint, the application must provide a new endpoint under the aps.endpoint node in the JSON representation:

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 URLs with the new base path such as http://apps.farm.com/ff7cf61b-7af2-4d1a-ad66-3f7e032086ed/<service-id>/.

APS Application Instance Upgrade

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. After receiving it, the APS controller updates certain 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"
         }
   }
}

Or supply only 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 the Application.

Unprovision Application Instances

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

The expected result:

• All APS resources related to the removed instance must be removed by the APS controller.

• The APS controller will calculate the right order of removal, starting from resources which are not strongly required by other resources.

• If some of the resources being deleted are strongly required (strong link) by some

  resources from other applications, he removal request will fail.

Application Alias Details

The /aps/2/application collection contains more operations than the aliased /aps/2/applications/{self-instance-id} collection.

The examples of using this alias are presented below.

Get a List of Application Services

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 is the APS application instance ID.

• aps.type is the APS application ID as specified in Metadata Descriptor (APP-META.xml).

• aps.endpoint is the URL of the APS application base endpoint.

• cloud.type is the ID of the APS type that implements the application resource schema and thus is used to control the APS application instance.

• cloud.name is the root service name.

• cloud.summary is the root service summary.

• cloud.schema is the internal ID of the APS type.

The other sections represent application services other than the root service.

Get Resource Details

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 representation will be the same as when using GET /aps/2/resource/{id} sent from a UI script.

Register Resources

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 necessary 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.

Update Resources

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 when using PUT /aps/2/resources/{id} sent from a UI script.

Change the Resource Status

An application can request the APS controller to change the current status of a resource provisioned by the application. It uses the same operation as above.

Example of a request:

PUT /aps/2/application/vpses/099a0e75-9427-4ea7-b1f1-331a81ecd57f

{
   "aps":{"id":"099a0e75-9427-4ea7-b1f1-331a81ecd57f"
   "status": "initializing"
   }
}

Unregister Resources

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

Link or Relink Resources

An application instance can require the linking or relinking of 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:

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 performing 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.

Unlink Resources

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 the removal of a required link, the operation will fail and the APS controller will return an error message similar to:

HTTP/1.1  500 Internal Server Error

{
   "error": "APS::Util::ConstraintException",
   "message": "The link 'offer' is mandatory for 'c76dcede-1785-42ad-8322-6f48474e9e69'."
}

← Application Endpoint

Deployment →