Application Instance

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.

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.

Applications Collection Briefly

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.

Application Alias Briefly

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.

Applications Collection Details

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.

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

Install Application Instance

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"
  }
}

Get Application Instance Properties

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

Update Application Instance

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:

Note

It is impossible to change anything else with this PUT request.

Change Application Instance Endpoint

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

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

Unprovision Application Instance

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.

Application Alias Details

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.

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

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

Register Resource

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.

Update Resource

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.

Change 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 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"
   }
}

Unregister Resource

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.