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 URI: http://basename[/major[.minor]] containing a prefix, a basename, and (optionally) a 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 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 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
• ‘.’ - 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 (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 a hosting platform or published in the APS catalog, you should take care of updating the version of 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.

Version Compatibility

Two APS types with the same BASENAME and MAJOR version are considered backwards compatible BWCB. It means a 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, is 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 should request that particular version.

Different MAJOR versions are considered to be NOT compatible, that is 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 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. 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 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 the 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 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, 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 →