API Best Practices

Fleet API high availability is guarenteed by dynamic IPs; addresses behind the DNS can change abruptly during regular operation. Excessive DNS TTL/caching can lead to stale DNS information. This can cause connection issues and errors.

The recommendation is to avoid altering the DNS TTL setting (use the default) to ensure that the DNS resolver is configured to follow the TTL values provided by the authoritative DNS servers.

Fleet API allows developers to get data from devices via API, these are meant to be used infrequently. The majority of these APIs have stringent rate limits in place for protection. To get data at regular interval use Fleet Telemetry which provides a direct and custom data stream in real time.

Following a Wake Up request vehicles may take 10s to 60s to come online. To determine when a vehicle is ready to be queried, it is advisable to check the "state" attribute returned by the Vehicle endpoint to ensure it is not "offline" or "asleep". Once confirmed, commands can be send to the vehicle. Note that if the vehicle is in a poor connectivity area 408 might be returned by the API despite the car being online and connected.

FleetAPI bearer token used for authorization are simple JWT tokens. Before calling the API, renew tokens if they are within a minute of expiration. Securely caching tokens is a viable option for distributed applications.

Fleet API is localized in multiple regions in accordance with local regulation (CCPA, GDPR, PIPL, etc.). The API may return some errors to guide developers, but it is the developers responsibility to comply with security, data privacy, data transfer, and data governance regulations.

Follow best security practices when manipulating private keys and secrets. Modern cloud providers offer key management services (such as AWS Key Management Service, Azure Key Vault, and Google Cloud Key Management Service) or hardware security module (HSM) solutions to create and manage private keys & secrets securely. It is important to not extract or transmit private keys over the network, particularly if they are not encrypted.

Timeouts can happen before or after a command is sent and executed in a vehicle, making it difficult to determine the vehicle's state when a timeout occurs. It is the developer's responsibility to ensure the vehicle is in the desired state. Most FleetAPI commands are stateful and can be safely retried, but some commands (such as honk_horn and media_next_track) may result in duplicated actions. Therefore, developers should exercise caution when retrying these commands to avoid unintended consequences.

Authentication requests like refresh token exchange should not exeed 20 req/sec for any application or account. Above this rate may result in an application being throttled or blocked.