L'API Zaptec est utilisée par de nombreux clients, partenaires et tiers, c'est pourquoi nous surveillons ses performances et sa stabilité en continu.
Afin de garantir à tous nos clients une bonne expérience lors de l'accès à leurs données, nous précisons dans cet article quelques recommandations et limites concernant l'API.
Évitez les sollicitations inutiles
Chaque appel à l'API ajoute une charge aux serveurs de Zaptec. Il est donc important que votre intégration évite d'appeler l'API inutilement.
Limites de sollicitations
Nous avons défini plusieurs limites au nombre d'appels à l'API afin de garantir une bonne performance à l'ensemble des utilisateurs.
Dépasser ces limites pendant une période donnée entraînera le code d'état "HTTP 429 - Too Many Requests".
Nous vous recommandons d'ajouter un délai entre deux appels ou de limiter le nombre de requêtes.
Vous ne devez pas utiliser l'API pour une collecte intensive de données sur les modifications. Il est plutôt recommandé d'utiliser un abonnement au bus de service qui fournira des mises à jour en temps quasi réel lorsque des changements se produisent, voir plus de détails ci-dessous.
En général, nous recommandons de limiter les appels à l'API à un maximum de 1000 requêtes par minute, pour tous les interfaces de l'API. Certains interfaces plus lourdes ont des restrictions plus importantes :
Limite stricte de 150 requêtes par 30 minutes, maximum de 30 par minute
- /api/chargers
- /api/installations
Service Bus
Pour votre intégration, deux abonnements au ServiceBus sont possibles :
- ServiceBus pour une Installation :
- un bus où sont poussés les messages liés à une installation donnée. Accessible à tout utilisateur ayant le rôle Utilisateur pour l'installation.
- ServiceBus pour un Groupe d'utilisateurs :
- pour les partenaires de service, un bus de Groupe d'utilisateurs peut être activé. Le bus enverra les mises à jour du statut des bornes de recharge auxquelles les utilisateurs du groupe sont associés.
Veuillez vous référer à l'article sur l'abonnement aux messages ici (connexion requise avec votre compte Zaptec Portal).
Recommandations pour les statuts des bornes de recharge
Il est recommandé de conserver l'état des bornes de recharge en local et d'utiliser cette information pour vos besoins. La méthode recommandée consiste à :
- Obtenir une liste d'installations/bornes de recharge auxquelles votre intégration a accès en utilisant /api/installation ou /api/chargers, ou en combinant avec /api/installation/{id}/hierarchy.
- Se connecter au ServiceBus de l'installation ou du groupe d'utilisateurs où les mises à jour en temps réel du statut des bornes de recharge dans vos installations ou des bornes de recharge accessibles par votre groupe d'utilisateurs seront fournies.
- Obtenir et stocker l'état de vos bornes de recharge en utilisant /api/chargers/{id}/state.
- Utiliser les événements du ServiceBus pour maintenir votre état local synchronisé avec l'état Zaptec.
Récupération des mêmes données
Dans cet exemple, nous considérons la récupération des données à partir de /api/chargers.
Cette commande "GET" renvoie toutes les bornes de recharge accessibles par votre utilisateur.
Ces données sont souvent les mêmes et c'est pourquoi nous recommandons de déplacer les données vers vos propres serveurs afin de réduire la nécessité de les demander régulièrement aux serveurs Zaptec.
Ce mode d'utilisation présente l'avantage de mettre les données en cache, au lieu d'effectuer des appels redondants à l'API.
De plus, si vous avez besoin d'intervalles courts entre deux requêtes gourmandes en ressources, comme /api/chargers, consultez les options de filtre disponibles pour de nombreuses requêtes. Vous pouvez les trouver et les tester ici.
Comme mentionné ci-dessus, la recommandation est de stocker une liste de vos bornes de recharge lors de la première requête et de l'utiliser pour les futures requêtes. Les bornes de recharge accessibles à votre utilisateur changeront de temps en temps, et vous devrez rafraîchir ces informations de temps en temps.
Notre recommandation est de le faire au maximum une fois par heure, ou lorsqu'une nouvelle borne de recharge inconnue est détectée. Pour rechercher des détails sur une borne de recharge spécifique, vous pouvez fournir le numéro de série de la borne de recharge dans le filtre de nom pour l'appel /api/chargers.
Réexécution exponentielle
Certaines commandes peuvent nécessiter la récupération d'une grande quantité de données depuis notre base de données. Pour celles-ci, nous recommandons d'implémenter des réexécutions avec un délai exponentiel.
Cela permet de laisser le temps pour le traitement des requêtes, en particulier en période de forte charge ou pour des requêtes gourmandes en ressources.
La mise en œuvre de cette fonctionnalité peut également éviter d'atteindre la limite de fréquence de requêtes sur votre compte Zaptec Portal.
Contrôle du comportement de vos systèmes informatiques
Nous avons une vue limitée de l'interaction entre les requêtes provenant de votre système et nos bornes de recharge.
Par conséquent, pour faciliter le dépannage en cas de problème, il est important de surveiller vos systèmes afin d'avoir une image plus claire de l'origine d'une requête.
Service Status Zaptec
Vous pouvez avoir une visualisation en temps réel de l'état de nos systèmes en vous rendant sur la page d'état du système Zaptec, située ici.