APS types must be differentiated by assigning a unique identifier for each type.
In this document:
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.
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/
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.
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.
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.
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
},
...
}
}