Stratosfy API: Introduction

Welcome to the Stratosfy Developer Portal. Here you will find information about the APIs we offer as well as how to use them. We have provided example language bindings in Shell and Python. You can view code examples in the dark area to the right, and you can switch the programming language with the tabs in the top right.

This API should be used responsibly. Stratosfy reserves the right to disable or throttle accounts deemed to be misusing this API. Please do not request data at a more frequent interval than your devices are reporting. Stratosfy reserves the right to return additional fields in responses.

Stratosfy Platform Diagram

Best Practices & Guidelines

This API should be used responsibly and should follow the best practices and guidelines set by Stratosfy.

  • Adhering to Rate Limits: Make API calls within the allowed frequency so as not to overload the system.
  • Efficient Use of Resources: Minimize redundant calls by fetching data only when needed and caching when appropriate.
  • Handling Data with Care: Use the data in ways that respect privacy and data protection regulations.

Irresponsible Use:
Excessive Polling, ignoring deprecated APIs, or data abuse can lead to account throttling or other enforcement.

Restrictions & Limitations

You may encounter restrictions or limitations, which may include one or more of the following:

  • Rate Limiting
    Impact: Users may be temporarily blocked from making further API calls if they exceed the number of requests allowed.
    Avoidance: Implement back-off strategies and adhere to any X-RateLimit headers.
  • Quotas on Resource Usage
    Impact: There may be a cap on the number of concurrent API calls, total calls per day, or the amount of data transferred.
    Avoidance: Optimize API usage by batching requests and retrieving only the necessary data.
  • Data Retention Policies
    Impact: Data might only be available for a limited period after it is archived or deleted.
    Avoidance: Ensure timely data retrieval and local storage if long-term access is needed.
  • API Versioning
    Impact: Users may need to migrate to newer versions of the API as older versions become deprecated.
    Avoidance: Regularly check for and migrate to the latest API versions.
  • Dependence on Device Reporting Frequency
    Impact: The frequency of data updates is contingent on the device's reporting interval.
    Avoidance: Align polling strategies with known device intervals to avoid over-polling.

Stratosfy API: Authentication

The Stratosfy REST API uses the client credentials portion of the OAuth2 specification to perform authentication and authorization. This requires that the client possess both a client identifier and a client "secret" (which should be kept confidential). These two together act like a username and password.

Stratosfy provides client credentials for API clients. Once you have your credentials, make a POST request to the /getBearerToken endpoint at https://platform.api.stratosfy.io/getBearerToken to obtain your access token.

Client Credentials Scope: The client credentials are bound to a specific Stratosfy account and user ID. They currently provide full (read-only) access to the data available to that user.

Using Client Credentials to Obtain an Access Token:
As per the OAuth2 specification (see RFC 6749 Section 4.4.2), pass grant_type=client_credentials in the request body (form-urlencoded) along with your client ID and client secret.

When calling the authentication endpoint, you must supply the following headers:

KEYVALUE
Acceptapplication/json
Content-Typeapplication/x-www-form-urlencoded
Content-Length(calculated dynamically)
Host(API server domain)

Stratosfy API: Global Types

  • Numbers: Byte, Integer (16/32/64 bit), Float (32/64 bit), Decimal
  • Date: ISO 8601 with time zone
  • Enums: Returned as strings in JSON

Stratosfy API: Error Handling

Error Code Meaning
400Bad Request – invalid payload.
401Unauthorized – invalid or missing token.
403Forbidden – operation not allowed.
404Not Found – resource does not exist.
500Internal Server Error.
503Service Unavailable – try again later.