Getting started with SmartSense API

Welcome to the SmartSense Developer Portal! SmartSense is a remote sensor monitoring system that provides solutions to help companies with quality control, employee productivity, asset protection, and compliance. The Developer Portal is where you will find information about the APIs (Application Programming Interfaces) that we offer as well as how to use them.  
 

A developer portal is a centralized repository that is primarily used by developers, but this platform also provides information that is useful to other teams such as Customer Success or Project Managers.

Authentication/Authorization Methods

Global Types

Error Handling

Data API

Report API

SCIM API v2

Best Practices & Guidelines

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

 

Responsible Use:

• Adhering to Rate Limits: Making API calls within the allowed frequency, ensuring you're not overloading the system. For instance, if the device reports data every 15 minutes, you should not poll for data more frequently than that.
• Efficient Use of Resources: Minimizing the number of calls by fetching data as needed and caching information where appropriate, rather than making redundant requests.
• Handling Data with Care: Using the data obtained from the API in a way that respects privacy and follows data protection regulations. 

Irresponsible Use: 

By adhering to SmartSense's guidelines, developers ensure that the API remains stable and efficient for everyone.

SmartSense reserves the right to disable or throttle accounts deemed to be misusing this API. It is acceptable to poll for new information, but please do not request data at a more frequent interval than your devices are reporting to SmartSense. 

SmartSense reserves the right to return additional fields in responses.  

Rate Limiting

Rate limiting is configured per account. Not all requests are rate limited; limits are applied based on your account configuration.
 

Rate Limit Details

When rate limiting is enabled for your account, limits are typically configured within a 60-second window using a Token Bucket algorithm. The Token Bucket algorithm allows for bursts of requests up to the limit, then refills tokens at a steady rate.

For example, an account might be configured with a limit of 1,000 requests per 60 seconds.

Rate Limit Headers

When your account has rate limiting enabled, API responses include the following headers:

• ratelimit Summary of limit, remaining requests, and reset time
  Example: limit=1000, remaining=847, reset=52
   
• ratelimit-policy The rate limiting policy in effect
  Example: 1000;w=60;policy="Token Bucket"
• ratelimit-limit Maximum number of requests allowed in the time window
  Example: 1000
• ratelimit-remaining Number of requests remaining in the current window 
  Example: 847
   
• ratelimit-reset Seconds until the rate limit window resets
  Example: 52

Handling Rate Limits

If you exceed your rate limit, the API will return an HTTP 429 (Too Many Requests) status code along with a Retry-After header indicating when you can retry the request.

1. Your application should: Monitor the ratelimit-remaining header to track available requests

2. Respect the Retry-After header value when a 429 response is received

3. Use the ratelimit-reset value to understand when your limit will refresh

4. Implement exponential backoff when rate limit errors occur

5. Cache API responses when appropriate to reduce unnecessary requests

Impact: Requests may be temporarily blocked if your account exceeds the configured number of requests within the time window.

Avoidance: Implement back-off strategies and monitor the rate limit headers to manage the frequency of requests effectively.

Restrictions & Limitations

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

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 that can be transferred.

Avoidance: Optimize API usage by batching requests and retrieving only the necessary data to stay within the set quotas.

Data Retention Policies

Impact: Data might only be available through the API 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 to ensure compatibility and access to the latest features.

Dependence on Device Reporting Frequency

Impact: The frequency of data updates is contingent on the device's reporting interval, which can affect the timeliness of the data retrieved.

Avoidance: Align polling strategies with the known device reporting intervals to ensure data is as fresh as possible without over-polling.