Previous topic

General Definitions

Next topic

Properties

DOCUMENTATION
Last updated 11-Aug-2016

APS Type ID

Type ID Definition

APS types must be differentiated by assigning a unique identifier for each type. To be globally unique, a type ID is specified in the format of URI: http://basename[/major[.minor]]. Examples:

http://www.aps-standard.com/infrastructure/pcs/1.1
http://www.parallels.com/poa/mailbox/2.0
http://www.parallels.com/poa/mailbox/exchange/1
http://aps-standard.org/samples/basic/vps

Note

Each APS Type identifier starts with the http:// prefix, no other protocol prefixes are supported.

Warning

If a package with a certain type ID is imported into a hosting platform or published in the APS catalog, you should take care of updating the type ID, when you add, remove, or change any component in the type. Only after that, you can use the updated package in the hosting platform or republish it to the APS catalog.

Basename

The basename element is basically a part of URI, which is essentially a domain and a /path/ that together are treated as a string constant uniquely identifying the APS Type. You can even use a domain name that is neither registered nor resolved in the Internet, but make sure the same URI is not used by another ISV in an APS package.

Note

Specifying a port number is not supported. A domain must be specified without a port number in it.

The following are examples of valid base APS type IDs:

http://www.aps-standard.com/infrastructure/pcs/
http://www.parallels.com/poa/mailbox/
http://www.parallels.com/poa/mailbox/exchange/

Version

The version element has the following structure: major[.minor]

Note

the minor element is optional and treated as ‘0’ when not present. It means these two expressions are equal: ‘3.0’ == ‘3’.

The version element can contain only the following characters:

  • ‘0-9’ - within MAJOR and MINOR sub-elements
  • ‘.’ - dot symbol as a separator between MAJOR and MINOR (when MINOR is present)

Note

The major and minor numbers are treated as separate integers and each number could be incremented higher than a single digit. Thus, 2.10 is a higher version than 2.2. Leading zeros (e.g., 01 ) must NOT be specified.

The following are examples of valid APS Types with specified versions:

http://www.aps-standard.com/infrastructure/pcs/1.1
http://www.parallels.com/poa/mailbox/2.0
http://www.parallels.com/poa/mailbox/exchange/1

Version Compatibility

Two APS types with the same BASENAME and MAJOR version are considered backwards compatible [BWCB]. It means a new interface http://www.parallels.com/mailbox/1.4 is compatible with http://www.parallels.com/mailbox/1.0 type, however the reverse [FWCB] is not true as illustrated by the following examples.

When APS type http://www.parallels.com/mailbox/1.0 is requested, it is possible to get the type http://www.parallels.com/mailbox/1.4 in response.

However, when APS type http://www.parallels.com/mailbox/1.5 is requested, is is NOT valid to return http://www.parallels.com/mailbox/1.4. Only older revisions of the APS type within the same MAJOR version are considered compatible.

Different MAJOR versions are considered to be NOT compatible, i.e. http://www.parallels.com/mailbox/1.0 and http://www.parallels.com/mailbox/2.0 are two different non-compatible types.

The following examples illustrate the cases when you would better use a minor update and when the major update is necessary.

Example 1: Minor Update

Initially there was a “vps” type containing a number of properties. It’s version is 1.0.

{
  "apsVersion": "2.0",
  "name": "vps",
  "id": "http://techdoc.apsdemo.tst/vpscloud/vps/1.0",
  ...
  "properties": {
    "name": {
      "type": "string",
    },
    ...
  }
}

The developer decided to add the optional property “description”. Since the property is not required, the resources will be backward compatible after the type update. That is why, the developer decided to do minor update to version 1.4, as follows.

{
  "apsVersion": "2.0",
  "name": "vps",
  "id": "http://techdoc.apsdemo.tst/vpscloud/vps/1.4",
  ...
  "properties": {
      "name": {
        "type": "string",
      },
      "description": {
        "type": "string",
      },
      ...
  }
}

Example 2: Major Update

Following up multiple requests from providers, the developer decided to make the “description” a required attribute. Evidently, the VPSes created earlier will not be compatible with the new type version, since they may do not have a description. That is why, the developer has to do a major update, e.g. to version 2.0 as follows.

{
  "apsVersion": "2.0",
  "name": "vps",
  "id": "http://techdoc.apsdemo.tst/vpscloud/vps/2.0",
  ...
  "properties": {
      "name": {
        "type": "string",
      },
      "description": {
        "type": "string",
        "required": true
      },
      ...
  }
}