Application Packaging Standard

Last updated 18-Mar-2019

Application Endpoint¶

In this document:

Operations
Resource Structure
Provision New Resource
Retrieve Resource Properties
Configure Resource
Unprovision Resource
Link Resources
Unlink Resources
Custom Operation

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

Link Resources ¶

General Rules¶

When linking a resource {resource1} with another resource {resource2} the APS controller addresses the POST request to the endpoint of the {resource1} service.

Request: POST {endpoint url}/{service1-id}/{resource1-id}/{relation}. The body contains the JSON representation of {resource2}.

Successful response: HTTP code 200

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

Example¶

Request for linking the context resource (service ID is contexts) with a VPS whose JSON representation is in the message body:

POST /suwizard1p/contexts/24bf448d-86b0-4c73-a9df-cf65655e81f1/vpses
APS-Application-ID:aa2b33a0-0dcd-42ab-9be4-c598339948bf
Host:endpoint.a.isv1.apsdemo.org
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:13975-6185

{
   "aps":
   {
      "type": "http://aps-standard.org/samples/suwizard1p/vps/1.1",
      "id": "b26cd680-4cad-4d7d-ad1b-28cdf4000691",
      "status": "aps:provisioning",
      "revision": 2,
      "modified": "2015-08-10T11:07:34Z",
      "subscription": "40396157-535d-4d8b-84f3-dd0e8ca05504",
      "package":
      {
         "id": "f19a107e-2cba-403b-bd5c-9b4105411cee",
         "href": "/aps/2/packages/f19a107e-2cba-403b-bd5c-9b4105411cee"
      }
   },
   "description": "Description",
   "hardware":
   {
      "CPU":
      {
         "number": 2
      },
      "diskspace": 16,
      "memory": 512
   },
   "name": "VPS102",
   "platform":
   {
      "OS":
      {
         "name": "centos6"
      }
   },
   "state": "Stopped",
   "userName": "Kim Kelvin",
   "context":
   {
      "aps":
      {
         "link": "strong",
         "href": "/aps/2/resources/24bf448d-86b0-4c73-a9df-cf65655e81f1",
         "id": "24bf448d-86b0-4c73-a9df-cf65655e81f1",
         "subscription": "40396157-535d-4d8b-84f3-dd0e8ca05504"
      }
   }
}

Response:

HTTP/1.1 200 OK
Content-Length:0
Connection:close
Content-Type:text/html

Unlink Resources ¶

General Rules¶

To unlink a resource {resource1} from another resource {resource2} the APS controller addresses the DELETE request to the endpoint of the {resource1} service.

Request: POST {endpoint url}/{service1-id}/{resource1-id}/{relation}/{resource2-id}

Successful response: HTTP code 204

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

Example¶

Request for unlinking an offer resource (service ID is offers) from a VPS:

DELETE /endpoint/offers/1745b633-59f8-428c-9930-e42b11558512/vpses/d27a726e-7c38-43c6-a2d3-c6c9211cfd74
APS-Application-ID:a9ccc96f-6be9-4e2e-baf8-468b2d68b71a
APS-Application-ID:a9ccc96f-6be9-4e2e-baf8-468b2d68b71a
APS-Controller-URI:https://10.28.99.192:6308/
APS-Instance-ID:a9ccc96f-6be9-4e2e-baf8-468b2d68b71a
APS-Version:2.2.0
APS-Identity-ID:8a1cc5b6-b786-4f65-aeb9-ac0d3523c3d1
APS-Transaction-ID:22734-1466

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

← Application

Application Instance →

Table Of Contents

Previous topic

Next topic

Application Packaging Standard

Application Endpoint¶

Operations ¶

Resource Structure ¶

Provision New Resource ¶

General Rules¶

Example¶

Retrieve Resource Properties ¶

General Rules¶

Example¶

Configure Resource ¶

General Rules¶

Example¶

Unprovision Resource ¶

General Rules¶

Example¶

Link Resources ¶

General Rules¶

Example¶

Unlink Resources ¶

General Rules¶

Example¶

Custom Operation ¶

General Rules¶

Example¶