Assets versioning

Important notes:

• Orbis Maps Assets API is currently in public preview.
• This API is powered by the TomTom Orbis Maps.
• See the TomTom Orbis Maps documentation for more information on Orbis Maps.
• See the Orbis Maps Assets API Migration page page for information on how to migrate and use the new Orbis Maps Assets API.
• Use of the Orbis Maps Assets API requires an API Key with access rights to Assets API and, depending on the requested assets, Map Display API and/or Traffic API.

Purpose

In the Assets API, assets versioning helps to manage and monitor modifications in map styles, sprites, glyphs, and fonts, providing consistency across different platforms. This page describes the components that a version consists of, and how they signify compatible and non-compatible changes in the style. As a user, it is essential to keep your style up to date, ensuring access to the latest features and visually enhancing improvements for an optimal user experience.

Assets versioning

In the Assets API, assets are versioned using the following convention, which is based on Semantic Versioning:

MAJOR.MINOR.PATCH-BUILD_NUMBER

The components of the version are:

• MAJOR: This represents the major version component and is incremented when backward incompatible changes are introduced to the assets.
• MINOR: This is the minor version component, which is incremented when new functionality is added in a backward compatible manner.
• PATCH: This denotes the patch version component, and it is increased when backward compatible bug fixes are introduced.
• BUILD_NUMBER: This is the build number of the version, incremented with every new build of the styles. It may introduce minor backward compatible bug fixes.

22.2.1-15

Using wildcards

A wildcard is a character that represents one or more other characters or values in various contexts. In the Assets API, the wildcard is represented by an asterisk (*). When incorporated into an asset version, the wildcard selects the most recent version component, ensuring the usage of the most up-to-date elements. The wildcard can replace the MAJOR, MINOR, or PATCH components, but not the BUILD_NUMBER.

While the use of a wildcard can provide users with the newest assets, it may pose a risk to the stability of a user's application when the wildcard replaces the MAJOR component of the version. It is recommended to use a wildcard as a replacement for the MINOR and PATCH components (e.g., MAJOR.*, MAJOR.MINOR.*) rather than replacing the MAJOR component.

Example

Let's imagine a situation that the following asset versions are available on the back-end:

122.2.1-15
222.1.2-1
322.1.1-1

The following diagram shows what version is chosen for each wildcard usage.

122.2.* -> 22.2.1-15
222.* -> 22.2.1-15
322.1.* -> 22.1.2-1
4* -> 22.2.1-15

Assets versioning and cache policy

The Assets API employs different caching directives based on the actual resource and whether the version contains wildcards.

• For all resources obtained by listing functionalities, the API's Cache-Control header is set to no-cache (a response can be stored in caches but must be validated with the origin server before each re-use).
• For all resources obtained by fetch functionalities, with standard versions without wildcards, the API's Cache-Control header is set to allow caching for 14 days (1209600 seconds). This means that any cached response can be reused without requiring revalidation for the entire 14-day period.
• For all resources obtained by fetch functionalities, with versions with wildcards, the API's Cache-Control header is set to no-cache and stale-if-error for 14 days. This means that the response can be stored in caches, but must be validated with the origin server before each re-use. However, when the error occurs in contacting the origin server, the response can be re-used for 14 days.