APS Type ID

APS types must be differentiated by assigning a unique identifier for each type.

Type ID Definition

Structure

To be globally unique, a type ID is specified in the format of a URI: http://basename[/major[.minor]] containing a prefix, a basename, and (optionally) the version. Examples:

http://www.aps-standard.com/infrastructure/pcs/1.1
http://www.odin.com/mailbox/2.0
http://www.odin.com/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.

Basename

The basename element is basically a part of the URI, which is essentially a domain and a /path/ that together are treated as a string constant which uniquely identifies 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 name 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.odin.com/mailbox/
http://www.odin.com/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

• The 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 can be incremented higher than a single digit. Therefore, 2.10 is a higher version than 2.2. Leading zeros (for example, 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.odin.com/mailbox/2.0
http://www.odin.com/mailbox/exchange/1

Warning

If a package with a certain type ID is imported into the platform or published in the application catalog, make sure you update the version of the type ID, when you add, remove, or change any component in the type. This also requires the update of the application ID. Only after that, you can use the updated package in the platform or republish it to the application catalog.

Version Compatibility

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

• When APS type http://www.odin.com/mailbox/1.0 is requested, it is possible to get resources of both types, version 1.0 and 1.4, in response.

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

Note

As follows from the above, to guarantee the return of the latest version of a resource, you must request that particular version.

Different MAJOR versions are considered to be not compatible, meaning http://www.odin.com/mailbox/1.0 and http://www.odin.com/mailbox/2.0 are two non-compatible types.

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

Example 1: Minor Update

Initially there was a “vps” type containing a number of properties. Its 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 a 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",
      },
      ...
  }
}

Warning

To use the new property, you should specify version 1.4 in your request. If you specify version 1.0, the APS controller will not find that property in the APS type version 1.0 and return an error message.

Example 2: Major Update

Following up multiple requests from providers, the developer decided to make the “description” a required property. Evidently, the VPSes created earlier will not be compatible with the new type version, because some of them do not have a description. That is why, the developer has to do a major update, for example, 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
      },
      ...
   }
}

← General Definitions

Properties →