Introduction
Bienvenue sur le portail des développeurs SmartSense ! SmartSense est un système de surveillance par capteurs à distance qui propose des solutions destinées à aider les entreprises dans les domaines du contrôle qualité, de la productivité des employés, de la protection des actifs et de la conformité. Le portail des développeurs vous permettra de trouver des informations sur les API (interfaces de programmation d’applications) que nous proposons, ainsi que sur leur utilisation.
Un portail développeurs est un référentiel centralisé principalement destiné aux développeurs, mais cette plateforme fournit également des informations utiles à d'autres équipes, telles que celles chargées de la réussite client ou les chefs de projet.
Table des matières
Bonnes pratiques et lignes directrices
Cette API doit être utilisée de manière responsable et conformément aux bonnes pratiques et aux recommandations établies par SmartSense.
Utilisation responsable :
Respect des limites de fréquence : effectuer des appels API dans les limites de fréquence autorisées, afin de ne pas surcharger le système. Par exemple, si l'appareil transmet des données toutes les 15 minutes, vous ne devez pas interroger le système plus fréquemment que cela.
Utilisation efficace des ressources : réduire au minimum le nombre d'appels en récupérant les données au fur et à mesure des besoins et en mettant les informations en cache lorsque cela est pertinent, plutôt que d'effectuer des requêtes redondantes.
Traiter les données avec soin : Utiliser les données obtenues à partir de l'API de manière à respecter la vie privée et à suivre les réglementations en matière de protection des données.
Utilisation irresponsable :
Interrogation excessive : le fait d'effectuer des requêtes API à une fréquence supérieure à celle de l'actualisation des données, ce qui peut surcharger les serveurs, nuire à la qualité du service pour les autres utilisateurs et entraîner éventuellement une limitation ou une désactivation de votre compte.
Ignorer les API obsolètes : Continuer à utiliser des points d'extrémité d'API obsolètes ou des fonctionnalités qui ont été marquées comme obsolètes peut entraîner une instabilité et des vulnérabilités en matière de sécurité.
Abus de données : L'utilisation des données à des fins autres que celles pour lesquelles elles ont été conçues, en particulier si elle viole la vie privée de l'utilisateur ou les politiques de l'entreprise.
En respectant les directives de SmartSense, les développeurs garantissent que l'API reste stable et performante pour tous.
SmartSense se réserve le droit de désactiver ou de limiter l'accès aux comptes jugés comme faisant un usage abusif de cette API. Il est acceptable d'interroger le service pour obtenir de nouvelles informations, mais veuillez ne pas demander de données à une fréquence supérieure à celle à laquelle vos appareils transmettent leurs données à SmartSense.
SmartSense se réserve le droit d'inclure des champs supplémentaires dans ses réponses.
Limitation du taux
La limitation du débit est configurée au niveau de chaque compte. Toutes les requêtes ne sont pas soumises à cette limitation ; les limites sont appliquées en fonction de la configuration de votre compte.
Détails sur la limitation du nombre de requêtes
Lorsque la limitation de débit est activée pour votre compte, les limites sont généralement configurées sur une fenêtre de 60 secondes à l'aide d'un algorithme de type « Token Bucket ». Cet algorithme autorise des pics de requêtes jusqu'à la limite fixée, puis recharge les jetons à un rythme constant.
Par exemple, un compte peut être configuré avec une limite de 1 000 requêtes toutes les 60 secondes.
En-têtes de limitation de débit
Lorsque la limitation de débit est activée sur votre compte, les réponses de l'API incluent les en-têtes suivants :
ratelimitRécapitulatif des limites, des demandes restantes et de l'heure de réinitialisation
Exemple :limite=1000, reste=847, réinitialisation=52
politique de limitation de débitLa politique de limitation du débit actuellement en vigueur
Exemple :1000 ; w=60 ; policy="Token Bucket"ratelimit-limitNombre maximal de requêtes autorisées pendant la plage horaire
Exemple :1000ratelimit-restantNombre de demandes restantes dans la fenêtre actuelle
Exemple :847
réinitialisation du limite de débitNombre de secondes avant la réinitialisation de la fenêtre de limitation de débit
Exemple :52
Gestion des limites de débit
Si vous dépassez votre limite de requêtes, l'API renverra un code d'état HTTP 429 (Too Many Requests) accompagné d'un Retry-After en-tête indiquant quand vous pouvez réessayer la requête.
1. Votre application doit : surveiller le ratelimit-restant en-tête permettant de suivre les demandes disponibles
2. Respecter les Retry-After valeur de l'en-tête lorsqu'une réponse 429 est reçue
3. Utilisez le réinitialisation du limite de débit valeur permettant de savoir quand votre limite sera actualisée
4. Mettre en place un recul exponentiel en cas d'erreurs liées à la limitation de débit
5. Mettre en cache les réponses de l'API lorsque cela est pertinent afin de réduire les requêtes superflues
Conséquence : les requêtes peuvent être temporairement bloquées si votre compte dépasse le nombre de requêtes défini au cours de la période considérée.
Prévention : mettez en place des stratégies de réduction progressive et surveillez les en-têtes de limitation de débit afin de gérer efficacement la fréquence des requêtes.
Restrictions et limitations
Vous pourriez être confronté à des restrictions ou à des limitations, qui peuvent inclure un ou plusieurs des éléments suivants :
Quotas d'utilisation des ressources
Impact : Le nombre d'appels API simultanés, le nombre total d'appels par jour ou la quantité de données pouvant être transférées peuvent être limités.
Éviter : Optimisez l'utilisation de l'API en regroupant les demandes et en ne récupérant que les données nécessaires pour rester dans les limites des quotas fixés.
Politiques de conservation des données
Impact : Les données peuvent n'être disponibles via l'API que pendant une période limitée après avoir été archivées ou supprimées.
Éviter : Assurer la récupération des données en temps utile et le stockage local si un accès à long terme est nécessaire.
Versionnement de l'API
Impact : Les utilisateurs peuvent être amenés à migrer vers des versions plus récentes de l'API au fur et à mesure que les anciennes versions deviennent obsolètes.
Éviter : Vérifier régulièrement les dernières versions de l'API et migrer vers celles-ci pour garantir la compatibilité et l'accès aux dernières fonctionnalités.
Dépendance à l'égard de la fréquence des rapports sur les dispositifs
Impact : La fréquence des mises à jour des données dépend de l'intervalle de rapport de l'appareil, ce qui peut affecter l'actualité des données extraites.
À éviter : Aligner les stratégies d'interrogation sur les intervalles de rapport connus des appareils afin de garantir que les données sont aussi fraîches que possible, sans pour autant les soumettre à une interrogation excessive.