All Products
Search

This Product

    HTTPDNS:API overview

    Document Center

    HTTPDNS:API overview

    Last Updated:Dec 15, 2025

    Introduction

    The APIs provided by the Android software development kit (SDK) can be categorized by feature as follows:

    • Configuration APIs: SDK initialization, security settings, performance optimization, and network adaptation.

    • Domain name resolution APIs: Synchronous, asynchronous, and non-blocking resolution, pre-resolution, and cache management.

    • Troubleshooting and tracing APIs: Session tracing, log management, and debugging support.

    • Custom resolution APIs: Synchronous, asynchronous, and non-blocking APIs for custom resolution.

    • Common data structure APIs: Resolution results, callback functions, custom cache TTL, and domain name resolution filters.

    The APIs are also categorized based on their support level:

    • Recommended APIs: These APIs are recommended for the current SDK version. They are optimized for functionality or user experience.

    • Deprecated APIs: These APIs are no longer recommended due to feature refactoring or design optimization. Some of these APIs may be removed in future versions. Migrate to the corresponding recommended APIs for better performance and stability.

    This topic describes all APIs in the HTTPDNS Android SDK and helps you quickly understand and use the features of the SDK.

    Configuration APIs

    Configuration APIs are used to initialize and configure the features of the HTTPDNS SDK. These features include service instance acquisition, cache policies, network parameters, and security settings. Use these APIs to customize the SDK's behavior and optimize resolution performance and security based on your application's needs.

    Recommended APIs

    Class

    Function declaration

    Description

    Introduced in version

    HttpDns

    getService(String)

    Get an HTTPDNS service instance

    2.6.3

    InitConfig.Builder

    setContext(Context)

    Set the application context

    2.6.3

    InitConfig.Builder

    setSecretKey(String)

    Set the signing key

    2.6.3

    InitConfig.Builder

    setAesSecretKey(String)

    Set the encryption key

    2.6.3

    InitConfig.Builder

    setEnableHttps(boolean)

    Specify whether to use the HTTPS protocol to communicate with the server

    2.2.2

    InitConfig.Builder

    setEnableExpiredIp(boolean)

    Specify whether to allow returning expired IP addresses

    2.2.2

    InitConfig.Builder

    setEnableCacheIp(boolean, long)

    Allow the use of local cache that has expired for a period of time

    2.4.3

    InitConfig.Builder

    setEnableCacheIp(boolean)

    Enable the local cache feature

    2.2.2

    InitConfig.Builder

    setPreResolveAfterNetworkChanged(boolean)

    Specify whether to automatically refresh the local cache when the network changes

    2.4.0

    InitConfig.Builder

    setTimeoutMillis(int)

    Set the resolution timeout threshold

    2.4.0

    HttpDnsService

    setAuthCurrentTime(long)

    Correct the signing time

    1.3.2

    InitConfig.Builder

    setRegion(Region)

    Set the region node during initialization

    2.4.2

    HttpDnsService

    setRegion(Region)

    Update the region node

    2.4.2

    HttpDnsService

    setRegion(String)

    Update the region node

    2.4.2

    InitConfig.Builder

    configCacheTtlChanger(CacheTtlChanger)

    Customize the cache duration for resolution results

    2.3.0

    InitConfig.Builder

    setNotUseHttpDnsFilter(NotUseHttpDnsFilter)

    Set a filter for domain names that do not use HTTPDNS for resolution

    2.4.0

    InitConfig.Builder

    setIPRankingList(List<IPRankingBean>)

    Set the domain names and probing ports for IP address selection

    2.3.2

    InitConfig.Builder

    setSdnsGlobalParams(Map<String, String>)

    Set global parameters for custom resolution

    2.4.0

    Deprecated APIs

    Class

    Function declaration

    Description

    Introduced in version

    Deprecated in version

    Removed in version

    HttpDns

    getService(Context, String)

    Get an HTTPDNS service instance

    1.3.2

    2.6.3

    -

    HttpDns

    getService(Context, String, String)

    Get an HTTPDNS service instance

    1.3.2

    2.6.3

    -

    HttpDnsService

    setHTTPSRequestEnabled(boolean)

    Specify whether to use the HTTPS protocol to communicate with the server

    1.3.2

    -

    2.4.0

    HttpDnsService

    setExpiredIPEnabled(boolean)

    Specify whether to allow returning expired IP addresses

    1.3.2

    -

    2.4.0

    HttpDnsService

    setCachedIPEnabled(boolean)

    Specify whether to enable persistence for cached resolution results

    1.3.2

    -

    2.4.0

    HttpDnsService

    setPreResolveAfterNetworkChanged(boolean)

    Specify whether to automatically refresh the local cache when the network changes

    1.3.2

    -

    2.4.0

    InitConfig.Builder

    setTimeout(int)

    Set the resolution timeout threshold

    2.0.2

    2.4.0

    -

    HttpDnsService

    setTimeoutInterval(int)

    Set the resolution timeout threshold

    1.3.2

    -

    2.4.0

    HttpDnsService

    setLogEnabled(boolean)

    Specify whether to enable log output

    1.3.2

    2.3.2

    2.4.0

    HttpDnsService

    setLogger(ILogger)

    Set a log callback

    1.3.2

    2.3.2

    2.4.0

    InitConfig.Builder

    setRegion(String)

    Set the region node during initialization

    1.3.2

    2.4.2

    -

    InitConfig.Builder

    setDegradationFilter(DegradationFilter)

    Set a filter for domain names that do not use HTTPDNS for resolution

    2.4.0

    2.4.0

    -

    HttpDnsService

    setIPRankingList(List<IPRankingBean>)

    Set the domain names and probing ports for IP address selection

    2.3.2

    -

    2.4.0

    HttpDnsService

    setIPProbeList(List<IPRankingBean>)

    Set the domain names and probing ports for IP address selection

    1.3.2

    2.3.2

    2.3.2

    HttpDnsService

    setSdnsGlobalParams(Map<String, String>)

    Set global parameters for custom resolution

    1.3.2

    -

    2.4.0

    Domain name resolution APIs

    Domain name resolution APIs are a core feature of the HTTPDNS SDK. They provide multiple resolution methods, including synchronous, asynchronous, and non-blocking resolution. The SDK supports dual-stack resolution for IPv4 and IPv6. It automatically selects the optimal resolution policy based on the network environment. It also provides pre-resolution and cache management features.

    Recommended APIs

    Class

    Function declaration

    Description

    Introduced in version

    HttpDnsService

    setPreResolveHosts(List<String>, RequestIpType)

    Set the list of domain names for pre-resolution

    2.4.0

    HttpDnsService

    getHttpDnsResultForHostSync(String, RequestIpType)

    Resolve a domain name synchronously. This blocks the thread.

    2.3.2

    HttpDnsService

    getHttpDnsResultForHostAsync(String, RequestIpType, HttpDnsCallback)

    Resolve a domain name asynchronously. The result is returned through a callback.

    2.4.0

    HttpDnsService

    getHttpDnsResultForHostSyncNonBlocking(String, RequestIpType)

    Perform synchronous, non-blocking resolution. This only checks the cache. If the cache does not exist, it returns empty.

    2.4.0

    HttpDnsService

    cleanHostCache(ArrayList<String>)

    Clear the cache for a specified list of domain names.

    2.2.2

    Deprecated APIs

    Class

    Function declaration

    Description

    Introduced in version

    Deprecated in version

    Removed in version

    HttpDnsService

    getIpByHostAsync(String)

    A synchronous, non-blocking API that resolves to a single IPv4 address.

    2.0.2

    2.3.2

    -

    HttpDnsService

    getIPv4ForHostAsync(String)

    A synchronous, non-blocking API that resolves to a single IPv4 address.

    2.3.2

    2.4.0

    -

    HttpDnsService

    getIPv6ForHostAsync(String)

    A synchronous, non-blocking API that resolves to a single IPv6 address.

    2.3.2

    2.4.0

    -

    HttpDnsService

    getIpsByHostAsync(String)

    A synchronous, non-blocking API that resolves to all resulting IPv4 addresses.

    2.0.2

    2.3.2

    -

    HttpDnsService

    getIPv4ListForHostAsync(String)

    A synchronous, non-blocking API that resolves to all resulting IPv4 addresses.

    2.3.2

    2.4.0

    -

    HttpDnsService

    getIPv6ByHostAsync(String)

    A synchronous, non-blocking API that resolves to a single IPv6 address.

    2.0.2

    2.3.2

    -

    HttpDnsService

    getIPv6sByHostAsync(String)

    A synchronous, non-blocking API that resolves to all resulting IPv6 addresses.

    2.0.2

    2.3.2

    -

    HttpDnsService

    getIPv6ListForHostASync(String)

    A synchronous, non-blocking API that resolves to all resulting IPv6 addresses.

    2.3.2

    2.4.0

    -

    HttpDnsService

    getAllByHostAsync(String)

    A synchronous, non-blocking API that resolves to all resulting IPv4 and IPv6 addresses.

    2.0.2

    2.3.2

    -

    HttpDnsService

    getHttpDnsResultForHostAsync(String)

    A synchronous, non-blocking API that resolves to all resulting IPv4 and IPv6 addresses.

    2.3.2

    2.4.0

    -

    HttpDnsService

    getIpsByHostAsync(String, RequestIpType)

    A synchronous, non-blocking API that resolves to all resulting IPv4 addresses.

    2.0.2

    2.3.2

    -

    HttpDnsService

    getHttpDnsResultForHostAsync(String, RequestIpType)

    A synchronous, non-blocking API that lets you specify the resolution type and returns all resolution results.

    2.0.2

    2.4.0

    -

    Troubleshooting and tracing APIs

    Troubleshooting and tracing APIs are used for problem diagnosis and performance monitoring. They provide features such as session tracing and log management. Use these APIs to obtain detailed information about the resolution process. This information helps developers with debugging and O&M engineers with troubleshooting, which improves application observability.

    Recommended APIs

    Class

    Function declaration

    Description

    Introduced in version

    HttpDnsService

    getSessionId()

    Get the session ID for the interaction with the HTTPDNS server in the current process

    1.3.2

    HttpDnsLog

    enable(boolean)

    Control the log output switch

    2.0.2

    HttpDnsLog

    setLogger(ILogger)

    Set a log callback interface

    2.0.2

    HttpDnsLog

    removeLogger(ILogger)

    Delete a log callback class

    2.0.2

    Custom resolution APIs

    Custom resolution APIs support passing extra parameters for domain name resolution to address specific business requirements. Use custom parameters to achieve fine-grained resolution control, such as passing business identities. This provides personalized resolution services for different scenarios.

    Recommended APIs

    Class

    Function declaration

    Description

    Introduced in version

    HttpDnsService

    getHttpDnsResultForHostSync(String, RequestIpType, Map<String, String>, String)

    A synchronous API that lets you specify the resolution type

    2.4.0

    HttpDnsService

    getHttpDnsResultForHostAsync(String, RequestIpType, Map<String, String>, String, HttpDnsCallback)

    An asynchronous API that lets you specify the resolution type

    2.4.0

    HttpDnsService

    getHttpDnsResultForHostSyncNonBlocking(String, RequestIpType, Map<String, String>, String)

    A synchronous, non-blocking API that lets you specify the resolution type

    2.4.0

    Deprecated APIs

    Class

    Function declaration

    Description

    Introduced in version

    Deprecated in version

    Removed in version

    HttpDnsService

    getIpsByHostAsync(String, Map<String,String>, String)

    A synchronous, non-blocking API that resolves to IPv4 results

    1.3.0

    2.3.2

    -

    HttpDnsService

    getHttpDnsResultForHostAsync(String, Map<String, String> , String)

    A synchronous, non-blocking API that resolves to IPv4 results

    2.0.2

    2.4.0

    -

    HttpDnsService

    getIpsByHostAsync(String, RequestIpType, Map<String,String>, String)

    A synchronous, non-blocking API that lets you specify the resolution type

    2.0.2

    2.4.0

    -

    HttpDnsService

    getHttpDnsResultForHostAsync(String, RequestIpType, Map<String, String>, String)

    A synchronous, non-blocking API that lets you specify the resolution type

    2.0.2

    2.4.0

    -

    Common data structure APIs

    Common data structure APIs define the core data types and callback interfaces used in the SDK. These include resolution result encapsulation, callback functions, filters, and configuration enumerations. These APIs provide a unified data model and interaction standard for all SDK features.

    Recommended APIs

    Class

    Function declaration

    Description

    Introduced in version

    HTTPDNSResult

    getHost()

    Get the resolved domain name

    1.3.2

    HTTPDNSResult

    getIps()

    Get the array of IPv4 addresses

    1.3.2

    HTTPDNSResult

    getIpv6s()

    Get the array of IPv6 addresses

    2.0.2

    HTTPDNSResult

    getExtras()

    Get the extra parameters returned from custom resolution

    1.3.2

    HTTPDNSResult

    isExpired()

    Check if the resolution result has expired

    2.0.2

    HttpDnsCallback

    onHttpDnsCompleted(HTTPDNSResult)

    Callback function for when resolution is complete

    2.4.0

    CacheTtlChanger

    changeCacheTtl(String, RequestIpType, int)

    Callback function to customize the cache TTL

    2.3.0

    NotUseHttpDnsFilter

    notUseHttpDns(String)

    Callback function to set domain names that do not use HTTPDNS for resolution

    2.4.0

    ILogger

    log(String)

    Log output API

    1.3.2

    Region

    -

    Region enumeration type

    2.4.2

    Deprecated APIs

    Class

    Function declaration

    Description

    Introduced in version

    Deprecated in version

    Removed in version

    DegradationFilter

    shouldDegradeHttpDNS(String)

    Set a filter for domain names that do not use HTTPDNS for resolution

    2.0.2

    2.4.0

    -