This topic describes how to integrate the DoH JSON API on the client side.
DoH JSON API integration flow
The following flowchart shows the domain name resolution process on the client side:
Design policies
The domain name resolution mechanism must follow these design policies:
Fallback policy
Although HTTPDNS is integrated with BGP Anycast and provides disaster recovery across multiple regions and data centers, we recommend that you adopt the following fallback policy to ensure that client-side domain name resolution remains unaffected in a worst-case scenario:
1. First, send a domain name query to HTTPDNS.
2. If an HTTPDNS query returns a non-200 status code or a connection timeout occurs, use the local DNS to resolve the domain name. The recommended timeout is 3 s.
Cache policy
To minimize the number of domain name resolution requests, cache the results locally. The cache rules are as follows:
1. Cache duration: Set the cache duration to a value between 60 s and 600 s.
2. Cache updates: Update the cache in the following two situations:
When the user's network status changes: When a client switches between a WWAN and a Wi-Fi network, the network provider of its access point may change. In this case, you must send a new domain name resolution request to HTTPDNS to obtain the optimal endpoint for the user's current network.
When the cache expires: When a cached domain name resolution expires, the client should send a new domain name resolution request to HTTPDNS to obtain the latest IP address for the domain name. To ensure that users can retrieve the latest IP address as soon as the cache expires, we recommend that you use a timer to update expired cache entries every minute.
IP optimization policy
After you send a domain name query to HTTPDNS and obtain the resolution results, you can perform IP optimization. This process involves caching the results, asynchronously testing the speed of each IP address using the socket or ping method, sorting the IP addresses by speed, and then updating the cache with the sorted results.
Notes
Do not set the cache TTL value too low (a minimum of 60 s) because frequent HTTPDNS requests can increase your costs.
Services that use HTTPDNS should retain the user's local DNS as a disaster recovery channel. If HTTPDNS is unavailable (due to an unstable network or issues with the HTTPDNS service), you can use the local DNS for fallback resolution.
Use the same domain name for different features whenever possible. Differentiate resources by URL. This reduces the number of domain name resolution requests and lowers your costs.
The recommended timeout for an HTTPDNS request is 2 s to 5 s.