Best practices for DoH JSON API integration

Client-side DNS resolution failures can cause service outages and increased latency. This document covers the fallback, caching, and IP optimization policies you need to implement when integrating the DoH (DNS over HTTPS) JSON API, so your app resolves domain names reliably and at the lowest possible cost.

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

HTTPDNS is integrated with BGP Anycast and provides disaster recovery across multiple regions and data centers. To ensure client-side domain name resolution remains unaffected when HTTPDNS is unreachable, implement the following fallback policy:

1. Send the domain name query to HTTPDNS first.

2. If HTTPDNS returns a non-200 status code or a connection timeout occurs, fall back to local DNS. The recommended timeout is 3 s.

Cache policy

Cache resolution results locally to minimize the number of domain name resolution requests.

Cache duration: Set the cache duration to a value between 60 s and 600 s.

Cache updates: Refresh the cache in the following two situations:

• Network status change: When a client switches between a WWAN and a Wi-Fi network, the access point's network provider may change. Send a new domain name resolution request to HTTPDNS to get the optimal endpoint for the user's current network.

• Cache expiry: When a cached entry expires, send a new domain name resolution request to HTTPDNS to retrieve the latest IP address. Use a timer to check and update expired cache entries every minute so users always get the latest IP address without delay.

IP optimization policy

After you get resolution results from HTTPDNS, run IP optimization:

1. Cache the results.

2. Asynchronously test the speed of each IP address using the socket or ping method.

3. Sort the IP addresses by speed.

4. Update the cache with the sorted results.

Implementation guidelines

• Keep the cache TTL at 60 s or higher. A lower TTL causes more frequent HTTPDNS requests and increases your costs.

• Services that use HTTPDNS should retain local DNS as a fallback channel. If HTTPDNS is unavailable due to an unstable network or a HTTPDNS service issue, local DNS handles resolution automatically.

• Use one domain name for multiple features and differentiate resources by URL path. Fewer domain names mean fewer resolution requests and lower costs.

• Set the HTTPDNS request timeout to 2 s–5 s.