DoH JSON API - Alibaba Cloud DNS - Alibaba Cloud Documentation Center

The DNS-over-HTTPS (DoH) JSON API provides URL endpoints for both TLS and non-TLS APIs.

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

Request method: GET. The request parameters are as follows:

Parameter	Type	Description	Example	Usage method and default value
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 proxy use, not applicable for regular clients
short	boolean	short=true or short=1	Optional, disabled by default
uid	string	uid is the Account ID in the console, not the Alibaba Cloud account ID	uid=9**9	Required, no default value
ak	string	ak is the AccessKey ID in 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 supports DNS ECS functionality (RFC7871), which passes the user's subnet information to the authoritative DNS for more accurate DNS resolution and traffic rerouting. Longer subnet masks provide more precise address information, while shorter masks offer better user privacy. A subnet mask length of "/24" is recommended.

Note

This parameter is designed for scenarios where a DNS proxy uses the DoH JSON API. In these scenarios, a user sends a DNS query to a DNS proxy. The proxy then uses this parameter to send the user's subnet information to HTTPDNS, which passes the information to the authoritative server.

For example, withsubnet=1.2.XX.XX/24, the authoritative server will receive the 1.2.XX.XX/24 address prefix information to help select the DNS path for the user.

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.

In this formula, Account ID is the string value of your account ID. For example, if your account ID is 9**9, the string is "9**9". ts is the timestamp of the current request. qname is the requested domain name. For more information about how to generate an AccessKey ID and AccessKey secret, see Create a key.

Key generation example

Note

Assume:

Account ID=5***4
AccessKey Secret=12345**
qname=aliyun.com
ts=1614927253
AccessKey ID=5***4_2155917885567****

key=sha256(5***412345**1614927253aliyun.com5***4_2155917885567****)

The generated key is:

key=*****ab77496a89c04de0a1e979bfee4b4678a0dcd57f4da1da83***a490f64b

Sample request

Note

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

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 in the DNS message header	0: noerror 1: formerr 2: servfail 3: nxdomain
TC	TC in the DNS message header, indicates whether truncation is possible	Usually false
RD	RD in the DNS message header, indicates whether recursion is desired	Usually true
RA	RA in the DNS message header, indicates whether recursion is available	Usually true
AD/CD	Corresponding flags in the DNS message header	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, refer to "About supported types for the type parameter" above	Such as: A, AAAA, TXT, CNAME, NS, SOA
TTL	Maximum cache time for the response value on the server, in seconds	3600
data	Response result, related to type	None

Short mode response example:

Using www.taobao.com as an example, when requesting an A record, the request URL is:

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

The response is as follows:

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

When requesting a CNAME record, the URL is:

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

The response is as follows:

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

Failed response

When a request fails, the HTTP response status code is 4xx/5xx, and a specific error code is returned for debugging or issue reporting. The result is represented in JSON format.

Failed response 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

Note

For more information about how to use the DoH JSON API to access HTTPDNS for domain name resolution, see DoH JSON API Best Practices.
We recommend using the SDK for access, as it includes signature code and requires no manual implementation. For SDK access, see Android SDK development guide and iOS SDK development guide.