The Zaptec API is used by many customers, partners and third parties, therefore we need to monitor the performance and stability of the system.
To ensure that all our customers continue to enjoy the same quality of experience in accessing their data, we have some recommendations and limits on the API.
Avoid unnecessary fetching
Any API calls coming into the API adds a load to the Zaptec backend. Because of this it is important that your integration avoid calling the API unnecessarily.
Rate Limits
We have several rate limits on our API calls to ensure all our customers can experience a high level of performance when using our API
Exceeding these limits during a particular time period will result in the status code
‘HTTP 429 – Too Many Requests‘
Please consider building in some wait time, adding your own throttling limit on requests or implementing exponential backoff in this event.
You should not use the API for aggressive polling for changes. Instead, it is recommended to use a service bus subscription that will provide near real time updates when changes occur, see more details below.
In general, we recommend an integration to limit API calls to maximum 1000 requests per minute, across all API endpoints. Some heavier endpoints have further restrictions:
Hard limit at 150 requests per 30 minutes, maximum 30 per minute
- /api/chargers
- /api/installations
Service Bus
There are two service bus subscriptions available for your integration:
- Installation service bus
-
- A message bus where messages for a given installation is pushed. Accessible to any user with User-role to the installation.
- User group service bus
-
- For partners, a user group service bus can be made accessible. The message bus will be provided state updates for all chargers accessible by your group.
Please refer to Message Subscription Article here (requires sign-in using your Zaptec Portal account)
Recommended way to maintain charging station state
It is recommended that your integration keeps the charging station state locally and use this for your purposes. The recommended way to do this is to:
- Get a list of installation/chargers that your integration has access to using /api/installation or /api/chargers, or combined with /api/installation/{id}/hierarchy
- Connect to the installation or user group service bus where real time updates for charger state in your installations or chargers accessible by your user group will be provided
- Get and store state for your chargers using /api/chargers/{id}/state
- Use events from service bus to keep your local state in sync with Zaptec state
Fetching same data
In this example, we consider the fetching of data from /api/chargers
This GET command returns all chargers accessible by your user.
This data is often the same and because of this we recommend moving the data to your own servers to reduce the need to request this regularly from Zaptec servers.
This use case would typically benefit from caching data, instead of redundantly making API calls.
Additionally, if there is a use case for a short interval between retries of resource intensive requests, such as /api/chargers, please ensure to review the available filter options associated with many of the commands. These can be found and tested here.
As mentioned above, the recommendation is to store a list of your accessible chargers on boot and use this for future reference. Chargers accessible to your user will from time-to-time change, and you will need to refresh this from time to time.
Our recommendation is that this is done at maximum once an hour, or when a new unknown charging station is detected. To lookup details for a specific charging station, the charger serial number can be provided in the nameFilter for the /api/chargers call.
Exponential Backoff
Certain commands may require our database fetch a lot of data, for these we recommend implementing retries with an exponential backoff.
This will allow time to let requests process, particularly in times of heavy traffic or resource intensive requests.
Implementing this feature may also prevent the rate limit on your Zaptec Portal account being reached.
Monitoring usage of your own devices
We have a restricted view of the interaction between the requests coming from your system and our chargers.
Therefore, to assist troubleshooting in the event of issues, it is important to monitor devices to have a clearer picture of where a request comes from.
Zaptec Service Status
Our systems can be monitored for service status at any time using the Zaptec System status page, located here