Introducción
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.
Índice
Buenas prácticas y directrices
This API should be used responsibly and should follow the best practices and guidelines set by SmartSense.
Uso responsable:
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.
Tratamiento cuidadoso de los datos: Utilizar los datos obtenidos de la API de forma que se respete la privacidad y se sigan las normas de protección de datos.
Uso irresponsable:
Excessive Polling: Making API requests more frequently than the data refresh rate, which can overload the servers, degrade service for others, and potentially lead to your account being throttled or disabled.
Ignorar las API obsoletas: Seguir utilizando puntos finales de API obsoletos o funciones que se han marcado como obsoletas puede provocar inestabilidad y vulnerabilidades de seguridad.
Abuso de datos: Utilización de los datos para fines ajenos a los previstos especialmente si vulnera la privacidad del usuario o las políticas de la empresa.
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.
Limitación de velocidad
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:
ratelimitSummary of limit, remaining requests, and reset time
Ejemplo:limit=1000, remaining=847, reset=52
ratelimit-policyThe rate limiting policy in effect
Ejemplo:1000;w=60;policy="Token Bucket"ratelimit-limitMaximum number of requests allowed in the time window
Ejemplo:1000ratelimit-remainingNumber of requests remaining in the current window
Ejemplo:847
ratelimit-resetSeconds until the rate limit window resets
Ejemplo: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.
Restricciones y limitaciones
You may encounter restrictions or limitations, which may include one or more of the following:
Cuotas de utilización de recursos
Impacto: Puede haber un límite en el número de llamadas concurrentes a la API, el total de llamadas por día o la cantidad de datos que se pueden transferir.
Evitar: Optimice el uso de la API agrupando las solicitudes y recuperando sólo los datos necesarios para no superar las cuotas establecidas.
Políticas de conservación de datos
Impacto: Los datos podrían estar disponibles a través de la API solo durante un periodo limitado después de ser archivados o eliminados.
Evitar: Garantizar la recuperación oportuna de los datos y su almacenamiento local si se necesita acceso a largo plazo.
Versionado de API
Repercusiones: Es posible que los usuarios tengan que migrar a versiones más recientes de la API a medida que las versiones anteriores queden obsoletas.
Evitar: Compruebe periódicamente si existen versiones más recientes de la API y migre a ellas para garantizar la compatibilidad y el acceso a las últimas funciones.
Dependencia de la frecuencia de notificación del dispositivo
Impacto: La frecuencia de actualización de los datos depende del intervalo de notificación del dispositivo, lo que puede afectar a la puntualidad de los datos recuperados.
Evitar: Alinee las estrategias de sondeo con los intervalos conocidos de notificación de los dispositivos para garantizar que los datos sean lo más recientes posible sin sondear en exceso.