Integration guide

1. Introduction

As described in Client integration overview, HTTPDNS provides domain name resolution services over HTTP to prevent DNS hijacking and improve resolution accuracy and stability. We strongly recommend using the official software development kit (SDK) for integration. However, in specific scenarios, such as deep feature customization or adapting to special network environments, you may need to implement domain name resolution using the HTTP API. Integrating with HTTPDNS using the HTTP API involves the following steps:

1. Activate the HTTPDNS service

2. Add the domain names to resolve

3. Obtain developer configurations, including the Account ID and keys

4. Obtain startup endpoints

5. Call the scheduling API

6. Perform domain name resolution

7. Dynamically update the list of resolution service IPs

You can perform the first three steps in the console. For more information about these steps, see Product workflow. The last four steps are part of the HTTP API integration flow. This topic describes the core concepts and flow for implementing high-availability DNS using the HTTP API.

2. Core concepts

• Scheduling service: An intelligent router component. It analyzes the client's source IP address for geolocation and network topology to provide an optimal list of resolution service nodes. This achieves load balancing and nearest access.

• Resolution service: The domain name resolution execution engine. It provides standard DNS query functions that convert domain names into the corresponding IP addresses. It supports A and AAAA record types.

• Startup endpoint: A pre-configured service discovery endpoint. It includes both an IP address and a domain name. It is used to establish the initial connection with the scheduling service and obtain a dynamically allocated list of resolution service nodes.

• Service IP: The address of a resolution server allocated by the scheduling service. It is an optimal node selected by a smart scheduling algorithm and is used to execute domain name resolution requests.

3. Integration steps

The HTTP API workflow includes four key steps that form a complete high-availability DNS resolution process:

1. Obtain startup endpoints - Embed multiple startup endpoints (IP addresses and fallback domain names) in the application as the entry points to access the scheduling service.

2. Call the scheduling API - Call the scheduling service API through a startup endpoint to obtain a list of nearby, healthy service IPs for subsequent resolution.

3. Perform domain name resolution - Use the obtained service IPs to call the domain name resolution API to complete the specific domain name-to-IP address mapping.

4. Dynamic update mechanism - Automatically update the service IP list under specific conditions, such as app startup, network transition, periodic updates, or resolution failure, to ensure continuous service availability.

   Note

   • Update on app cold start.

   • Update when switching network environments.

   • Update at least once every 8 hours.

   • Update immediately if all service IPs in the list fail to resolve after retries.

The core advantage of this workflow design is that it achieves high-availability DNS resolution through multiple endpoints and dynamic scheduling:

• Multiple endpoint guarantee: Ensures service reachability by embedding multiple startup endpoints. This prevents a single point of failure from affecting the entire service.

• Dynamic scheduling optimization: Dynamically obtains optimal service IPs through the scheduling API to achieve nearest access and failover.

This approach not only enables the HTTPDNS service to prevent DNS hijacking (direct IP connection, no reliance on local DNS) but also ensures high availability when some service IPs are blocked, under intense DDoS attacks, or facing extreme natural disasters.

4. Best practices

Implementing a high-performance, high-availability HTTPDNS client using the HTTP API is a technically challenging task. Developers must handle multilayered complexity. This ranges from redundant management of startup endpoints and intelligent calls to the scheduling service, to local caching of resolution results and failover mechanisms. Each part requires careful design and implementation. To lower the implementation barrier and difficulty, see Best practice recommendations.

5. Network library adaptation

After you obtain DNS resolution results through the HTTP API, you must correctly apply these IP addresses to the application's network library to enable direct IP connections for HTTP/HTTPS requests. To simplify the integration work for developers, HTTPDNS provides in-depth adaptation for mainstream network libraries:

• Android platform: Complete adaptation solutions for network libraries such as OkHttp, HttpClient, and HttpURLConnection.

• iOS platform: Integration guidance for network libraries such as NSURLSession, AFNetworking, and Alamofire.

• HarmonyOS platform: Adaptation implementations for native system network APIs and mainstream third-party network libraries.

These adaptation solutions not only solve the technical challenges of direct IP connections but also handle key technical details, such as HTTPS SNI, certificate validation, and Host header settings. This ensures stability and security in complex network environments.

For detailed network library integration implementations, see the documentation for the respective platforms:

• Android network library integration reference

• iOS network library integration reference

• HarmonyOS network integration reference

6. Summary

This topic described the core architecture and implementation flow for achieving high-availability HTTPDNS resolution using the HTTP API. For more information about the specific implementation, see the following documents: Startup endpoints, Scheduling service API, Domain name resolution API, and Best practice recommendations.