Skip to content

General Concepts

URLs, Regions and Environments

Each API has its own endpoint which is documented on the introduction page. The URL always follows this pattern:

%%{init: {'theme': 'dark'}}%%
graph TD
    subgraph "API URL Structure"
        URL["https://[api-name].[region].<br/>[environment].savr.saveris.net<br/>/[api-version]/[resource]"]
    end

    subgraph "Components"
        API["api-name"] --> |" "| API_EX["device-management-api,<br/>data-api,<br/>psc-api,<br/>tds-real-time-api"]
        REG["region"] --> |" "| REG_OPT["eu - Europe<br/>am - America<br/>ap - Asia-Pacific"]
        ENV["environment"] --> |" "| ENV_OPT["i - Integration/Testing<br/>p - Production"]
        VER["api-version"] --> |" "| VER_FMT["v1, v2, v3, etc.<br/>(endpoint specific)"]
    end

    URL --> API
    URL --> REG
    URL --> ENV
    URL --> VER

    style URL stroke:#6e7681,stroke-width:2px
    style API stroke:#6e7681
    style REG stroke:#6e7681
    style ENV stroke:#6e7681
    style VER stroke:#6e7681

You need to replace the values marked by <> with the following information:

API Name

The API name is provided on the respective overview page of each API. Please refer to the related documentation and change log of the specific API for more details.

Region

We have three regions where our APIs are deployed. Choose the region closest to your location to minimize request latency. The available regions and their shortcuts are:

  1. "eu" for European region
  2. "am" for American region
  3. "ap" for APAC region (Asia-Pacific)

Use the shortcut in the URL.

Environment

We distinguish our API endpoints by their environment. The following environments are available:

  1. "i" for integration. Its main purpose is for testing and contains test accounts.
  2. "p" for production. This environment contains all our real customer data and should be used for real applications.

Example

A real API endpoint that addresses the Device Management API in the europe region and on the integration environment would look like this: https://device-management-api.eu.i.savr.saveris.net

API Types and Versioning

We offer two types of APIs:

  • REST APIs: Used for standard create, read, update, and delete operations
  • WebSocket APIs: Used for real-time communication

The REST APIs provide versioned endpoints for operations. Examples include the Device Management API and Data API.

The Push API is used for real-time communication and is not versioned.

REST API Versioning Strategy

Our REST APIs follow an endpoint-specific, path-based versioning approach. This means:

  1. Each endpoint within an API can evolve independently
  2. Version numbers are included in the URL path
  3. Different endpoints within the same API may have different available versions

The URL pattern for versioned endpoints is:

https://<api-name>.<region>.<environment>.savr.saveris.net/{api-version}/resource

Example of Endpoint Versioning

A single API might contain multiple endpoints with different available versions:

GET https://<api-name>.<region>.<environment>.savr.saveris.net/v1/example-endpoint-first
GET https://<api-name>.<region>.<environment>.savr.saveris.net/v2/example-endpoint-first
GET https://<api-name>.<region>.<environment>.savr.saveris.net/v3/example-endpoint-first
GET https://<api-name>.<region>.<environment>.savr.saveris.net/v1/example-endpoint-second

In this example: - example-endpoint-first has evolved through three versions (v1, v2, v3) - example-endpoint-second is currently only available in v1

Version Selection

We recommend always using the newest available version of each endpoint. In the example above: - For example-endpoint-first, use v3 - For example-endpoint-second, use v1

Version Lifecycle

When a new version of an endpoint is released: 1. The previous version remains available for backward compatibility 2. Older versions may eventually be deprecated with advance notice 3. Each endpoint follows its own versioning lifecycle

Caution

The Device Management API has a unique versioning structure where most endpoints are available at the root path (implicitly v1), while some specific endpoints are available under the /v2/ path. This historical structure is maintained for backward compatibility.

WebSocket API (Push API)

The Push API uses WebSocket protocol for real-time, bidirectional communication. Unlike our REST APIs, the Push API is not versioned using URL paths. Any changes to the Push API are designed to be backward compatible.

CORS Support

Cross-Origin Resource Sharing (CORS) is supported by all our APIs, allowing them to be safely called from web applications in different domains.

API Compatibility Commitment

We strive to maintain backward compatibility when evolving our APIs. When introducing new versions of endpoints, we commit to:

  1. Keeping older versions functional for a reasonable transition period
  2. Providing clear documentation of changes between versions
  3. Announcing deprecation schedules well in advance

What Next?

Now that you understand our API structure and versioning approach, you can proceed to the specific API documentation to learn about available endpoints and their usage.