Application Packaging Standard

Last updated 18-Mar-2019

Version Management

Introduction

Since the platform and its embedded APS controller are continuously evolving through a number of versions, developers of APS application should take into account capabilities of the APS API versions (hereafter APS version) they are going to integrate their applications with. This allows them to make applications compatible with a selected APS version or even make application adaptive to various APS versions.

Note

1. APS versions are backward compatible, meaning the newer APS versions support APS applications designed for older APS versions.

  1. The ‘APS version’ and ‘APS controller version’ terms are interchangeable in this guide.

In addition to this document, also pay attention to the following sources for more details about the respective parts of the APS infrastructure:

APS Version Discovery

There are two ways of getting the current APS version as briefly presented below and explained in more details in the Operating Versions in PHP Runtime document.

APS Version REST Header

APS PHP runtime on APS endpoint hosts gets the current APS version in each REST request initiated by the APS controller. The latter sends the APS-Version header, for example:

POST /endpoint/vpses

"APS-Version":"7.3.0"

{ ... }

Note

The APS controller does not send this header in response to application requests or when communicating with an application UI.

Version Request

An application can request the APS controller for the supported APS versions using the following format:

GET /aps

In response, the APS controller sends the following in the message body:

{
   "versions": {
      "7.4": {
         "version": "7.4.0",
         "href": "/aps/7.4",
         "features": {
            "navigation": {
               "vars": [ "filter", "collection", "required" ],
               "view-plugin": "true"
            },
            "async": {
               "customOperation": true
            },
            "rql": [ "and()", "or()", "not()", "eq()", "ne()", "ge()", "le()", "lt()", "gt()",
               "like()", "in()", "out()", "true", "false", "true()", "false()", "empty()",
               "null()", "select()", "limit()", "sort()", "implementing()", "composing()"
            ]
         }
      },
      ...
   }
}

From this response, an application can get and then use the following data:

APS Controller Endpoint Versions

The APS controller is backward compatible, meaning it supports requests requesting a previous APS version.

If an application works in the APS PHP runtime environment, the latter sends all requests to the APS controller endpoint that supports the newest APS version.

However, an application can change this default behaviour by requiring a certain supported APS version to be used in all its requests. Thus, an application can send a request to any of the supported versions, for example:

GET /aps/7.4/resources

Get more details about implementation of the version control functionality in the APS PHP runtime environment.