All Products
Search
Document Center

JSON API for DoH

Last Updated: May 27, 2021

You can use the following URLs to call the JSON API for DNS over HTTPS (DoH). Both Transport Layer Security (TLS) and non-TLS API operations are provided.

https://dns.alidns.com/resolve?

https://alidns_ip/resolve?

http://dns.alidns.com/resolve?

http://alidns_ip/resolve?

Notice

alidns_ip is the A record of dns.alidns.com and can be one of the following IP addresses: 223.5.5.5 and 223.6.6.6.

Request method: GET

Request parameters

Parameter

Type

Description

Instance

Required/Optional and default value

name

string

The domain name in the request.

name=www.taobao.com.

Required. No default value.

type

integer

The request type.

type=1

Optional. Default value: 1.

edns_client_subnet

IP

ECS IP

edns_client_subnet=1.2.3.4/24

Used by the DNS proxy. This parameter does not apply to common clients.

short

boolean

Specifies whether to enable the short mode.

short=true or short=1

Optional. The short mode is disabled by default.

uid

string

The user ID. You can obtain the value from Account ID in the DNS console.

uid=9999

Optional.

did

string

The ID of the device.

did=afck0100

Optional.

edns_client_subnet parameter:

The edns_client_subnet parameter is designed to support EDNS Client Subnet (ECS) that is specified in the RFC 7871 specifications. ECS is a DNS extension that forwards the subnet information of users to the authoritative DNS server to achieve accurate DNS resolution and traffic scheduling. A long mask provides accurate address information, but a short mask better protects user privacy. We recommend that you use 24 as the mask length.

Note: This parameter is designed for scenarios in which the DNS proxy uses the JSON API for DoH. After the DNS proxy receives DNS queries from a user, it uses the edns_client_subnet parameter to pass the subnet information of the user to Alibaba Cloud Public DNS. Then, Alibaba Cloud Public DNS passes the subnet information to the authoritative DNS server.

For example, if the value of edns_client_subnet is 1.2.3.4/24, the authoritative DNS server selects a DNS link for the user based on the prefix of 1.2.3.4/24.

Values of the type parameter

Record type

ID

Description

Example (taobao.com and www.taobao.com used in the example)

A

1

An IPv4 record that maps a domain name to an IPv4 address.

101.37.183.171

NS

2

A name server record.

ns1.taobao.com.

CNAME

5

An alias record that associates a domain name with another domain name.

www.taobao.com.danuoyi.tbcache.com.

SOA

6

A Start of Authority (SOA) record that contains administrative information about a zone.

ns4.taobao.com. hostmaster.alibabadns.com. 2018011109 3600 1200 3600 360

TXT

16

A TXT record.

"v=spf1 include:spf1.staff.mail.aliyun.com -all"

AAAA

28

An IPv6 record that maps a domain name to an IPv6 address.

240e:e1:f300:1:3::3fa

Sample requests

http://dns.alidns.com/resolve?name=www.taobao.com.&type=1

Sample responses

{
    "Status":0,  
    "TC":false,
    "RD":true,
    "RA":true,
    "AD":false,
    "CD":false,
    "Question": {       // Request segment
        "name":"www.taobao.com.",
        "type":1
    },
    "Answer": [         // Response segment
        {
            "name":"www.taobao.com.",
            "TTL":45,
            "type":5,
            "data":"www.taobao.com.danuoyi.tbcache.com."
        },
        {
            "name":"www.taobao.com.danuoyi.tbcache.com.",
            "TTL":45,
            "type":1,
            "data":"47.246.24.234"
        },
        {
            "name":"www.taobao.com.danuoyi.tbcache.com.",
            "TTL":45,
            "type":1,
            "data":"47.246.24.233"
        }
    ]
    // The Authority segment. Data in this segment must be consistent with data in the Answer segment. 
    // The Additional segment. Data in this segment must be consistent with data in the Answer segment.
    // The edns_client_subnet parameter can be set to 1.2.3.4/24.  
}

The following table describes the return values.

Parameter

Description

Example

Status

RCODE of the DNS packet header.

0: noerror

2: servfail

3: nxdomain

TC

TrunCation (TC) of the DNS packet header. This parameter specifies whether the packet can be truncated.

false (This is the value in most cases.)

RD

Recursion Desired (RD) of the DNS packet header. This parameter specifies whether recursion is desired.

true (This is the value in most cases.)

RA

Recursion Available (RA) of the DNS packet header. This parameter specifies whether recursion is available.

true (This is the value in most cases.)

AD/CD

The identifier of the DNS packet header.

false (This is the value in most cases.)

Question

The DNS request segment.

Answer

The DNS response segment.

name

The domain name. Both Question and Answer contain the domain name.

www.taobao.com.

type

The request type. For more information, see Values of the type parameter.

TTL

The maximum duration for which the response value is cached in the server, in seconds.

3600

data

The response result, which is related to the type parameter.

Example of the response in short mode:

In short mode, responses that correspond to the type parameter in the request are extracted.

For example, if the DNS record type in the request for www.taobao.com is the A record, the following request Uniform Resource Locator (URL) is used:

http://223.5.5.5/resolve?name=www.taobao.com&type=A&short=1

The following code shows the response:

["221.229.203.214","61.155.221.227","221.229.203.213"]

If the DNS record type in the request for www.taobao.com is the canonical name (CNAME) record, the following request URL is used:

http://223.5.5.5/resolve?name=www.taobao.com&type=CNAME&short=1

The following code shows the response:

["www.taobao.com.danuoyi.tbcache.com."]

Failure response:

If the request fails, the HTTP status code is 4xx or 5xx and the error code for debugging or error reporting is returned. The result is displayed in the JSON format.

Failure response example:

{
    "code":"UrlParameterError"
}

The following table describes the error codes.

Error code

HTTP status code

Description

UrlParameterError

400

The error message returned because the parameter format is invalid.

NoPermission

401

The error message returned because user authentication failed.

UrlPathError

404

The error message returned because the URL is invalid.

NoResponse

500

The error message returned because no response is returned within a specified period of time.

Note: You can call the JSON API for DoH on your client applications or mobile apps to resolve DNS records.