We are reviewing our technical solutions and specifications to enable integrations that are scalable and resilient. This will lead to a tiered integration service that meets certain service level expectations that can grow with your business needs. We will announce these changes in good time to allow a smooth transition for all integrators. If you have any questions, please reach out to your regional Zaptec support.
The Zaptec API is used by many users, customers, and third-party integrators. To do this efficiently, 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 operating their service, we have some recommendations and limits on the API.
Tip:
Our systems can be monitored for service status at any time using the Zaptec System status page.
Avoid Unnecessary Fetching
Any API calls coming into the API add a load to the Zaptec backend. It is therefore 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 . You should not use the API for aggressive polling for changes.
We have implemented an API peak rate limit per account of 10 requests per second.
Exceeding these limits during a particular time period will result in the status code:
‘HTTP 429 – Too Many Requests‘
We ask that you please consider:
- building-in some wait time,
- adding your own throttling limit on requests,
- or implementing exponential backoff in this event.
Recommendation:
Use a service bus subscription that will provide near real-time updates when changes occur.
Exponential Backoff
Certain commands may require our database to 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 from being reached.
Service Bus
There is an installation service bus subscription available for your integration: A message bus where messages for a given installation are pushed. This feature is accessible to any user with a User-role to the installation. Learn more. (requires sign-in using your Zaptec Portal account).
Maintaining Charging Station State
We suggest that your integration keeps the charging station state locally and uses 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/chargers will be provided (Accessible by your user group).
-
Get and store the state for your chargers using /api/chargers/{id}/state
- Note: The chargers /{id}/state endpoint utilises a 15 second cache
- 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. Since this data is often the same, we recommend moving the data to your own servers to reduce the need to request this regularly from Zaptec's servers. Chargers accessible to your user may change, so you will need to refresh this from time to time.
If you have a use-case for short intervals 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 in Swagger.
Recommendation:
Do this is at a maximum of once an hour, or when a new unknown charging station is detected. (To look up details for a specific charging station, the charger serial number can be provided in the nameFilter for the /api/chargers call.
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, in the event of troubleshooting issues, it is important to monitor devices to have a clearer picture of where a request comes from.
Updated