Alibaba Cloud DNS:JSON API for DoH

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

• https://223.5.5.5/resolve?name=Domain name&type=Record type&uid=Account ID&ak=AccessKey ID&key=****&ts=Timestamp

• http://223.5.5.5/resolve?name=Domain name&type=Record type&uid=Account ID&ak=AccessKey ID&key=****&ts=Timestamp

• https://223.6.6.6/resolve?name=Domain name&type=Record type&uid=Account ID&ak=AccessKey ID&key=****&ts=Timestamp

• http://223.6.6.6/resolve?name=Domain name&type=Record type&uid=Account ID&ak=AccessKey ID&key=****&ts=Timestamp

Request parameters

Request method: GET. The following table lists the request parameters.

edns_client_subnet parameter

The edns_client_subnet parameter is designed to support ECS that is specified in the RFC 7871 specifications. ECS is a DNS extension that forwards the subnet information about users to authoritative DNS servers to improve the accuracy of DNS resolution and traffic scheduling. A long mask provides more accurate address information, but a short mask better protects user privacy. We recommend that you use /24 as the mask length.

Values of the type parameter

Algorithm used for generating the key parameter for authentication

key = sha256(uid+userKey+ts+qname+ak)

Note: The plus sign (+) indicates that the strings are concatenated.  

In the preceding code, the value of the uid parameter is a string that is converted from a number. For example, if the ID of the user is 9**9, set the value of the uid parameter to 9**9 as a string. The value of the userkey parameter is the AccessKey secret that is obtained on the Public DNS page of the Alibaba Cloud DNS console. The value of the ts parameter is also a string that is converted from a number. The value of the qname parameter is the domain name that the user wants to resolve. The value of the ak parameter is the AccessKey ID that is obtained on the Public DNS page of the Alibaba Cloud DNS console.

Key generation sample

Sample request

Sample response

{
    "Status":0,  
    "TC":false,
    "RD":true,
    "RA":true,
    "AD":false,
    "CD":false,
    "Question": {       // The request segment.
        "name":"www.taobao.com.",
        "type":1
    },
    "Answer": [         // The 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.XX.XX"
        },
        {
            "name":"www.taobao.com.danuoyi.tbcache.com.",
            "TTL":45,
            "type":1,
            "data":"47.246.XX.XX"
        }
    ]
    // 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.
    //Optional. The edns_client_subnet parameter can be set to 1.2.XX.XX/24.  
}

The following table describes the parameters in the response.

Example of the response in short mode:

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

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

The following code shows the response:

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

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

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

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"
}

Error codes