Application Packaging Standard

Last updated 18-Mar-2019

Application Endpoint

Operations

The following table contains a list of operations that the APS controller can call through APS application endpoints.

Method Path Description
POST /{service-id} Provision a resource
GET /{service-id}/{resource-id} Get resource properties
PUT /{service-id}/{resource-id} Configure a resource
DELETE /{service-id}/{resource-id} Unprovision a resource
POST /{service-id}/{resource-id}/{relation} Link resources
DELETE /{service-id}/{resource-id1}/{relation}/{resource-id2} Unlink resources
POST|PUT|GET|DELETE /{service-id}/{resource-id}/{operation-path} Custom operation
POST /{app-service-id}/{resource-id}/upgrade Update APS application instance
GET /{service-id}/$default Get default properties
GET /{service-id}/$schema Get resource schema
GET /{service-id}/$configurations Get available configurations

An application is available for the APS controller usually through a single APS application HTTPS REST endpoint. In some cases, more endpoints can be used.

Each application service that is a factory of resources within a specific type is presented as a separate URL. For example, if the APS application base endpoint is https://endpoints.apsdemo.org/app1/, then the service, whose ID defined in metadata is service1, will be available on https://endpoints.apsdemo.org/app1/service1/.

Resource Structure

On the interface between the APS controller and APS application endpoint, APS resources are represented as JSON objects described in Type Definition. Generally, an APS resource is presented in the following common format:

{
    "aps": { "id": "<id>", "type": "<type>" },
    ... /* configuration */ ...
    ... /* links */ ...
}

Resource properties:

Property Type Description
aps.id string Resource unique identifier, UUID
aps.type string APS type ID
<configuration> complex type Resource properties as defined in its APS type
<link> relation link Named link to another resource or other resources

This is an example of APS resource representation:

{
   "aps": {
      "type": "http://www.aps-standard.org/infrastructure/virtual-environment/1",
      "id": "16004e17-1604-49ee-a842-13c7daf93750"
   },

   "hostname": "my.host.com",
   "name": "myve",
   "description": "My cool VE",

   "hardware": {
      "bandwidth": 1024,
      "cpu": {
         "number": 1,
         "power": 2700
      },
      "diskspace": 2048,
      "memory": 2048
   },

   "platform": {
      "arch": "i386",
      "os": {
         "name": "Linux",
         "version": "centos-6"
      }
   },

   "status": {
      "state": "stopped",
      "transition": "starting"
   },

   "sample": {
      "aps": {
         "link": "strong",
         "href": "/aps/2/resources/66f7c299-174b-4508-bc45-fcbf81252ad5"
      }
   },

   "backups": {
      "aps": {
         "link": "collection",
         "href": "/aps/2/resources/66f7c299-174b-4508-bc45-fcbf81252ad5/links?rel=backups"
      }
   }
}

Provision New Resource

General Rules

When provisioning a resource through an endpoint, the APS controller expects the application to meet the following rules:

  • If the application sends back the “HTTP/1.1 200 OK” return code and there is no body in the response, it means the application has successfully created the new resource with the specified properties.
  • If the application sends back the “HTTP/1.1 200 OK” return code with the body containing a JSON object with some resource properties, the APS controller interprets it as if the application has successfully created the resource, but the application assigned its own values to the properties returned in the body. In its resource database, the APS controller will set the returned properties to the values assigned by the application.

Request: POST {app endpoint url}/{service-id}

Successful response: application returns HTTP code 200, and, optionally, a body with resource JSON representation.

Error response: error message and HTTP error code, for example, error 500.

Example

Request:

POST https://endpoint.a.isv1.apsdemo.org/endpoint75319/vpses
APS-Controller-URI:https://10.31.86.75:6308/
APS-Identity-ID:9adb598a-4f97-4a28-b502-71f25d3402a3
APS-Instance-ID:74f752fb-6150-44d2-8c98-e987882411e8
APS-Request-Phase:sync
APS-Transaction-ID:15438-39947
Content-length: ...

{
     "aps": {
          "type": "http://aps-standard.org/samples/offer-counter-user-func-and-link/vps/1.1",
          "id": "87504a7e-4617-4379-91ee-6b069009816c",
          "status": "aps:provisioning",
          "revision": 2,
          "modified": "2015-05-25T14:25:57Z",
          "package": {
                  "id": "c6c16a96-18c5-4090-8e99-c76358525571",
                  "href": "/aps/2/packages/c6c16a96-18c5-4090-8e99-c76358525571"
          }
     },
     "name": "VPS 22",
     "description": "new VPS",
     "hardware": {
          "CPU": {
                  "number": 2
          },
          "diskspace": 32,
          "memory": 128
     }
}

Successful Response (with empty body):

HTTP/1.1 200 OK
Connection:close
Content-Length:2
Content-Type:application/json

If the application returns a JSON object in its response body containing some properties, the APS controller will set the respective resource properties to the values returned by the application.

Error Response:

HTTP/1.1 500 Internal Server Error
Date: Tue, 17 Mar 2015 16:02:39 GMT
Server: Apache/2.2.15 (CentOS)
X-Powered-By: APS PHP Runtime 2.1-283
Cache-Control: no-cache, must-revalidate
Expires: 0
Content-Length: 295
Connection: close
Content-Type: application/json

{
  "code": 500,
  "type": "Rest::RestException",
  "message": "Can't provide VPS: diskspace is exceeded for subscription.",
  "details": {
             "error": "APS::Util::Exception",
             "message": "Can't provide VPS: diskspace is exceeded for subscription."
  }
}

Retrieve Resource Properties

General Rules

In the platform, the retrieve method is used to retrieve resource usage. The method returns the requested data.

Request: GET {app endpoint url}/{service-id}/{resource-id}

Successful Response: HTTP code 200 and requested data in JSON format.

Error Response: HTTP error code, for example, error 500, and error message.

Example

Request:

GET https://endpoint.a.isv1.apsdemo.org/endpoint42150/contexts/95715450-ec90-47e8-9b70-9f22cbb3a783
APS-Controller-URI:https://10.31.86.75:6308/
APS-Instance-ID:cd14aaa9-d05c-41fa-9122-505ca4c7d25c
APS-Transaction-ID:28821-6
APS-Version:2.0
Accept: application/json

Successful Response:

HTTP/1.1 200 OK
Date: Tue, 17 Mar 2015 15:50:50 GMT
Server: Apache/2.2.15 (CentOS)
X-Powered-By: APS PHP Runtime 2.1-283
Cache-Control: no-cache, must-revalidate
Expires: 0
Content-Length: 1227
Connection: close
Content-Type: application/json

     {
       "aps": {
         "type": "http://aps-standard.org/samples/offer-counter-user2/context/8.0",
         "id": "fd3a7c38-7675-4712-9d22-4f56d4e78100"
       },
       "name": "My Company",
       "diskusagetotal": {
         "usage": 2334,
         "limit": 23424
       },
       "memoryusagetotal": {
         "usage": 34234,
         "limit": 23455
       },
       "PU_HSSmall": {
         "usage": 1481
       },
       "PU_HS_Large21": {
         "usage": 40375,
         "limit": null
       },
       "PU_HS_Large211": {
         "usage": 1234,
         "limit": 200000
       },
       "cloud": {
         "aps": {
           "link": "strong",
           "href": "/aps/2/resources/ce749c5a-08d6-4298-bdf3-12083a19612d",
           "id": "ce749c5a-08d6-4298-bdf3-12083a19612d"
         }
       },
       "account": {
         "aps": {
           "link": "strong",
           "href": "/aps/2/resources/6884b50e-a5b7-4d3b-814d-1b0682a7f2f5",
           "id": "6884b50e-a5b7-4d3b-814d-1b0682a7f2f5"
         }
       },
       "subscription": {
         "aps": {
           "link": "strong",
           "href": "/aps/2/resources/642730ee-8fa4-4973-b215-27356cd7f8d3",
           "id": "642730ee-8fa4-4973-b215-27356cd7f8d3"
         }
       },
       "vpses": {
         "aps": {
           "link": "collection",
           "href": "/aps/2/resources/fd3a7c38-7675-4712-9d22-4f56d4e78100/vpses"
         }
       }
     }

Error Response:

HTTP/1.1 404 Not Found
Date: Tue, 17 Mar 2015 16:02:39 GMT
Server: Apache/2.2.15 (CentOS)
X-Powered-By: APS PHP Runtime 2.1-283
Cache-Control: no-cache, must-revalidate
Expires: 0
Content-Length: 321
Connection: close
Content-Type: application/json

{
   "code": 404,
   "type": "Rest::RestException",
   "message": "Specified resource `fd3a7c38-7675-4712-9d22-4f56d4e78100` is not found.",
   "details": {
      "error": "APS::Util::Exception",
      "message": "Specified resource `fd3a7c38-7675-4712-9d22-4f56d4e78100` is not found."
   }
}

Configure Resource

General Rules

When updating a property through an endpoint, the APS controller expects the application to meet the Configuration Rules. These are the rules for the usual cases:

  • If the application accepts the new value or changes the property to another value, it must return the property with the new value assigned to it. In its resource database, the APS controller assigns the returned value to the property.
  • If the application missed the property in its response, the APS controller interprets it as if the the property cannot be changed. In this case, the APS controller leaves the property in its resource database intact.

Request: PUT {endpoint url}/{service-id}/{resource-id}

Successful response: HTTP code 200, and, optionally, JSON representation of the resource.

Error response: HTTP error code, for example error 500, and error message.

Example

Request:

PUT https://endpoint.a.isv1.apsdemo.org/endpoint75319/vpses/87504a7e-4617-4379-91ee-6b069009816c
APS-Controller-URI:https://10.31.86.75:6308/
APS-Identity-ID:9adb598a-4f97-4a28-b502-71f25d3402a3
APS-Instance-ID:74f752fb-6150-44d2-8c98-e987882411e8
APS-Transaction-ID:16976-39995
Content-length: 817

{
  "aps":
  {
    "type": "http://aps-standard.org/samples/offer-counter-user-func-and-link/vps/1.1",
    "id": "87504a7e-4617-4379-91ee-6b069009816c",
    "status": "aps:ready",
    "revision": 4,
    "modified": "2015-05-25T14:47:51Z",
    "package":
    {
      "id": "c6c16a96-18c5-4090-8e99-c76358525571",
      "href": "/aps/2/packages/c6c16a96-18c5-4090-8e99-c76358525571"
    }
  },
  "description": "test descr",
  "hardware":
  {
    "CPU":
    {
      "number": 2
    },
    "diskspace": 32,
    "memory": 128
  },
  "name": "vps new info"
}

Successful response (with body):

HTTP/1.1 200 OK
APS-Controller-URI:https://10.31.86.75:6308/
Content-Type:application/json
Connection:close
Content-Length: 141

{
  "aps":
  {
          "id": "87504a7e-4617-4379-91ee-6b069009816c",
  },
  "name": "New name"
}

In the above response, the APS controller requested the application to set the name property to “vps new info”, but the application returned another value - “New name”. In its database, the APS controller must set the “name” to “New name”, that is it must agree with the application.

Unprovision Resource

General Rules

When removing a resource through an endpoint, the APS controller sends the DELETE request and the 204 code in response.

Request: DELETE {endpoint url}/{service-id}/{resource-id}

Successful response: HTTP code 204

Error response: HTTP error code, for example error 500, and error message.

In case of error response, the APS controller will keep the resource in the aps:unprovisining status.

Example

Request:

DELETE https://endpoint.a.isv1.apsdemo.org/endpoint75319/vpses/7ab1be46-a02c-414c-a44a-88b199ba9047
APS-Controller-URI:https://10.28.99.192:6308/
APS-Instance-ID:aa2b33a0-0dcd-42ab-9be4-c598339948bf
APS-Version:2.2.0
APS-Identity-ID:bcabf9fb-6894-49a5-bdb4-d597f28d1ddd
APS-Transaction-ID:11525-5825'

Successful response:

HTTP/1.1 204 No Content

Custom Operation

General Rules

If the APS controller needs to run a custom operation exposed by an application service on /{service-id}, it must send the REST request to /{service-id}/{resource-id}/{operation}. In the REST request, the APS controller must use the verb announced in the declaration of the operation. Respectively, it can be either POST, PUT, GET, or DELETE request.

Request: POST|PUT|GET|DELETE {endpoint url}/{service1-id}/{resource1-id}/{operation}

Successful response: HTTP code 200 and optionally response body if it is declared in the operation.

Error response: HTTP error code, for example error 500, and error message.

Example

A backup application declares an operation that returns a list of passed backup operations:

"getBackupList": {
   "verb": "GET",
   "path": "/getBackupList",
   "response": {
     "contentType": null,
     "type": "string",
     "items": null
   }
}

Respectively, a request from the APS controller for the list of backups must look as follows:

GET /vpsbackup/processes/83351d69-6c4d-46f4-9d9f-3a70ab17063a/getBackupList
APS-Controller-URI:https://10.28.99.192:6308/
APS-Instance-ID:a22e7346-4ef8-4e11-936c-cbafd00dc61c
APS-Version:2.2.0

Successful response:

HTTP/1.1 200 OK

[
   {
      "backup_id":"1",
      "bkp_datetime":"2015-08-10 14:18:01",
      "type":"F","state":"SUCCESS","size":"50"
   },
   {
      "backup_id":"2",
      "bkp_datetime":"2015-08-10 15:18:01",
      "type":"I",
      "state":"Scheduled",
      "size":null
   }
]