DoH JSON API

Endpoints

• https://223.5.5.5/resolve?name=domain&type=record type&uid=AccountID&ak=AccessKey ID&key=****&ts=timestamp

• http://223.5.5.5/resolve?name=domain&type=record type&uid=AccountID&ak=AccessKey ID&key=****&ts=timestamp

• https://223.6.6.6/resolve?name=domain&type=record type&uid=AccountID&ak=AccessKey ID&key=****&ts=timestamp

• http://223.6.6.6/resolve?name=domain&type=record type&uid=AccountID&ak=AccessKey ID&key=****&ts=timestamp

Request parameters

Method: GET. Parameters:

Parameter	Type	Description	Example	Usage and default
name	string	Domain name in the request	name=www.taobao.com	Required, no default value
type	string	About supported types for the type parameter	type=A	Optional, no default value
edns_client_subnet	IP	ECS IP	edns_client_subnet=1.2.XX.XX/24	For DNS proxies only
short	boolean	short=true or short=1	Optional, disabled by default
uid	string	Account ID from the console (not the Alibaba Cloud account ID)	uid=9**9	Required, no default value
ak	string	AccessKey ID from the console	ak=test	Required, no default value
ts	string	Timestamp	Unsigned integer, seconds since January 1, 1970	ts=1614927253 Required, no default value
key	string	Hash string for authentication	Signature generated using AccessKey Secret	key=fb321ab77496a89c04de0a1e979bfee4b4678a0dcd57f4da1da83****490f64b Required, no default value
did	string	Device ID	did=afck0100	Optional

About the edns_client_subnet parameter

The edns_client_subnet parameter implements DNS ECS (RFC7871), passing user subnet information to the authoritative DNS for accurate resolution and traffic rerouting. Longer subnet masks provide more precise addressing; shorter masks improve privacy. A /24 mask length is recommended.

About supported types for the type parameter

Record type	ID	Remarks
A	1	IPv4 address
NS	2	NS record
CNAME	5	Domain CNAME record
SOA	6	ZONE SOA record
TXT	16	TXT record
AAAA	28	IPv6 address
PTR	12	PTR record, used for reverse DNS lookup
MX	15	Mail exchange record
SRV	33	SRV record specifies host and port for specific services
CAA	257	CAA record is a security measure to prevent incorrect issuance of HTTPS certificates

Algorithm for generating the authentication parameter key

key = sha256(AccountID+AccessKey Secret+ts+qname+AccessKey ID)

Note: The plus sign (+) represents string concatenation, not the actual "+" character. 

Account ID is the string value of your account ID (e.g., "9**9"). ts is the current request timestamp. qname is the requested domain name. To generate an AccessKey pair, follow Create a key.

Key generation example

Sample request

Sample response

{
    "Status":0,  
    "TC":false,
    "RD":true,
    "RA":true,
    "AD":false,
    "CD":false,
    "Question":{       // Request section
        "name":"www.taobao.com.",
        "type":1
    },
    "Answer":[         // Response section
        {
            "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.XX.XX"
        },
        {
            "name":"www.taobao.com.danuoyi.tbcache.com.",
            "TTL":45,
            "type":1,
            "data":"47.246.XX.XX"
        }
    ]
    //"Authority" Authority section, if data exists, format is the same as Answer field 
    //"Additional" Additional section, if data exists, format is the same as Answer field
    // Optional "edns_client_subnet":"1.2.XX.XX/24"  
}

Response value description

Field name	Description	Example
Status	RCODE from the DNS header	0: noerror 1: formerr 2: servfail 3: nxdomain
TC	TC flag: whether truncation is possible	Usually false
RD	RD flag: whether recursion is desired	Usually true
RA	RA flag: whether recursion is available	Usually true
AD/CD	DNS header flags	Usually false
Question	DNS request field	None
Answer	DNS response field	None
name	Domain name, included in both Question and Answer	www.taobao.com
type	Request type as listed in About supported types for the type parameter	Such as: A, AAAA, TXT, CNAME, NS, SOA
TTL	Maximum cache time on the server, in seconds	3600
data	Response data (varies by type)	None

Short mode response example:

Example A record request for www.taobao.com:

https://223.5.5.5/resolve?name=domain&type=A&uid=AccountID&short=1&ak=AccessKey ID&key=****&ts=timestamp

Response:

["221.229.XX.XX","61.155.XX.XX","221.229.XX.XX"]

CNAME record request:

https://223.5.5.5/resolve?name=domain&type=CNAME&uid=AccountID&short=1&ak=AccessKey ID&key=****&ts=timestamp

Response:

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

Failed response

Failed requests return HTTP 4xx/5xx with a JSON error code for debugging or issue reporting.

Example:

{
 "code":"UrlParameterError"
}

Error code list

Error code	HTTP status code	Description
UrlParameterError	400	Request parameter format error
NoPermission	401	Authentication failed
UrlPathError	404	URL error
NoResponse	500	Request timeout, no response