HTTPDNS:Domain name resolution API

1. Overview

Resolving domain names using the HTTP API involves two steps: 1) obtain the resolution endpoint, and 2) send a resolution query using the API. This topic focuses on the second step: using the resolution API.

The domain name resolution API supports single and batch domain name resolution. It also supports optional signing and encryption of resolution parameters. The process of using this API is as follows:

1. Determine the resolution parameters: a list of domain names, the client IP address (optional), and the resolution type (IPv4 or IPv6).

2. Determine the request method: decide whether to use batch resolution, signing, or encryption for the resolution request.

3. Encrypt parameters (optional): Calculate the ciphertext of the resolution parameters.

4. Sign the request: Calculate a signature for the fields that require signing using the signing algorithm.

5. Send the request: Append the resolution parameters, account ID, and signature to the URL and send it to the server.

6. Parse the response: Retrieve the resolution result from the response message returned by the server.

This topic focuses on the request and response specifications for the HTTP API. It covers parameter definitions, encryption and signing rules, and the response structure. The main sections are as follows:

• API format: Describes the API access format, including the HTTP method, path, and general constraints.

• Parameters: Describes the request parameters, including their meanings, whether they are required, and whether they are included in signing or encryption.

• Parameter encryption: Describes how to encrypt request parameters and send them to the server in the enc field.

• Request signing: Describes the signature calculation process, including the parameters to be signed and the sorting rule.

• API response: Describes the response message structure and how to decrypt the message in encrypted mode.

2. API format

The resolution API supports access over http or https. The API format is as follows:

• Service URL: http(s)://{endpoint}/v2/d? + {request_parameters}

• Request method: GET

3. Parameters

This resolution API uses request parameters to define domain name resolution tasks and control the encryption and signing processes. You can set parameters to perform resolution in various combinations, such as plaintext or ciphertext, signed or unsigned, and for single or batch domain names.

3.1 Parameter list

The API supports plaintext and encrypted transmission modes. You can use the m parameter to control the encryption method. The following table lists all supported request parameters.

3.2 Request parameter examples

• Signed plaintext request

GET /v2/d?id=139450&dn=www.example1.com,www.example2.com&exp=1755526729&cip=192.168.1.1&q=4,6&m=0&sdns-param1=param1&s=20325751683ca72d1dfce8c279b97bc8d42c10436b3510a5dda600aeb71f4897 HTTP/1.1

• Signed ciphertext request

GET /v2/d?id=139450&exp=1755527315&&m=2&enc=93ce1ccf1057a0418636ee0d45e2f9308623e4adbcc3bc0f99dcf948da678a3a1abac4922b860dad056fb7abb812de9d26284331853cbbf896a7d461e4d6978679bd34de617f21a20b23a27033c3cd332c0286267a1a14848bda266bd3d3d04a818c10dad3ae98df5bd2681691e5886b7bf95731b2622f8b4d684c&s=895a578136065f95f9c38433757cab6878dfd23ab2011e02a7f33a19556864f1 HTTP/1.1

4. Parameter encryption (optional)

The domain name resolution API supports encrypting resolution parameters, including dn, cip, q, and sdns-*. This protects the confidentiality of request parameters even in non-HTTPS environments. The following steps describe how to encrypt the resolution parameters.

4.1 Build the string to encrypt

Store the fields to be encrypted, such as dn, cip, q, and sdns-*, in JSON format.

• The fields can be in any order.

• Optional parameters can be omitted.

• Both keys and values must be strings.

4.2 Select an encryption algorithm

This API supports two encryption algorithms: AES-GCM-128 and AES-CBC-128. The following table describes their differences and scenarios.

4.3 Get the key and IV

The security of the AES encryption algorithm depends on the key and the initialization vector (IV). You can obtain them in the following ways:

• secretKey:

  • Obtain it from Developer configuration in the console.

  • Length: 128 bit

  • The console returns a 32-character hex string. Before use, hex-decode the key to convert it to a binary key.

  • Example: 82c0af0d0cb2d69c4f87bb25c2e23929

• IV (initialization vector):

  • AES-GCM mode: 96 bit

  • AES-CBC mode: 128 bit

  • Generate a new IV using a secure random number generator before each request to ensure encryption security.

  • Example: 7322e81466eea91d69e7f735 (Hex-decode the value before encryption).

4.4 Perform encryption

1. Encrypt the JSON string using the selected encryption algorithm. The encryption parameters are as follows:

   Parameter	AES-CBC-128 (m=1)	AES-GCM-128 (m=2)
   String to encrypt	String to encrypt (UTF-8 encoded)	String to encrypt (UTF-8 encoded)
   Algorithm	AES-CBC-128	AES-GCM-128
   Key length	128 bits (16 bytes)	128 bits (16 bytes)
   IV length	128 bits (16 bytes)	96 bits (12 bytes)
   Padding mode	PKCS#7 padding	No padding required

2. Concatenate the IV and the ciphertext in order.

   1. The first few bytes are the IV (12 bytes for AES-GCM mode, 16 bytes for AES-CBC mode).

   2. The rest is the ciphertext.

3. Hex-encode the combined byte sequence.

4.5 Ciphertext request example

Assume that you need to resolve the domain names www.example1.com and www.example2.com with dual-stack resolution, a custom parameter of param1=value1, and a client IP address of 192.168.1.1. If you choose the AES-GCM-128 algorithm, the encryption process is as follows:

1. Build the string to encrypt.

   {
     "dn":"www.example1.com,www.example2.com",
     "q":"4,6",
     "sdns-param1":"value1",
     "cip":"192.168.1.1"
    }

2. Obtain the key and IV.

   • Key: 82c0af0d0cb2d69c4f87bb25c2e23929

   • IV: 006fe5011c9c2bf94a14f276

   Note

   • The key and IV here are examples. In a production environment, see 4.3 Obtain the key and IV.

3. Perform encryption to generate the following ciphertext.

   006fe5011c9c2bf94a14f2765e987d4df2139141ff71b9f79d71a8e8b4b0592b10c32c4f2f662a0f3d5aa125910148effa6e088d7e4cdb02907e85fa463b8f1a8eaeb0e6e86dc2fe12ada1c5b1560b585a8f6f913d6c4a77c0dcacec84e28fb7d2fdc4cb39e284fc4627b22da5202cc0a20201bcd9c2d6f4f63936

4. Final resolution request.

   GET /v2/d?id=xxxxx&m=2&enc=006fe5011c9c2bf94a14f2765e987d4df2139141ff71b9f79d71a8e8b4b0592b10c32c4f2f662a0f3d5aa125910148effa6e088d7e4cdb02907e85fa463b8f1a8eaeb0e6e86dc2fe12ada1c5b1560b585a8f6f913d6c4a77c0dcacec84e28fb7d2fdc4cb39e284fc4627b22da5202cc0a20201bcd9c2d6f4f63936 HTTP/1.1

5. Request signing (recommended)

You can use the authentication mechanism to enhance identity authentication and prevent potential fraudulent use. This section describes how to calculate the signature parameter s and construct the request for the HTTPDNS API. This helps ensure that resolution requests can be verified by the server and are tamper-proof. Request signing includes two steps: constructing the string to sign and calculating the signature.

5.1 Construct the string to sign

1. Generate a timestamp exp for when the signature expires.

2. Collect all key-value pairs that are part of the signature.

3. Sort them in ascending ASCII order by key (case-sensitive).

4. Concatenate them into a single-line string in the key=value format, separated by & characters.

5.2 Calculate the signature

• Algorithm: HMAC-SHA256

• Key: Obtain the 32-character hex string from Developer configuration in the console. Before use, hex-decode the key to obtain the actual 128-bit key.

• Input: The UTF-8 binary representation of the string to sign.

• Output: A lowercase, 64-character hex-encoded string.

5.3 Request signing example

Assume that you need to resolve the domain names www.example1.com and www.example2.com with dual-stack resolution, a custom parameter of param1=value1, and a client IP address of 192.168.1.1. If you send the request in plaintext, the signing process is as follows:

1. Original request parameters

   Parameter	Value
   dn	www.example1.com,www.example2.com
   exp	1755568414
   cip	192.168.1.1
   q	4,6
   m	0
   sdns-param1	value1

2. Concatenate into the string to sign

   cip=192.168.1.1&dn=www.example1.com,www.example2.com&exp=1755568414&id=139450&m=0&q=4,6&sdns-param1=value1

3. Calculate the signature

   • Signing key: 30b736b6d999700c5f589361fa4da44c

   • Generated signature: d931cea7222c861ab5f73b1f628e6fc782f00cf5f50faca678ce154b0263fdd0

   Note

   • The signing key here is an example. Obtain the actual signing key from Developer configuration.

4. Final resolution request

   GET /v2/d?id=139450&dn=www.example1.com,www.example2.com&exp=1755568678&cip=192.168.1.1&q=4,6&m=0&sdns-param1=value1&s=d931cea7222c861ab5f73b1f628e6fc782f00cf5f50faca678ce154b0263fdd0 HTTP/1.1

6. API response

After the server receives a valid resolution request from the client, it analyzes the request parameters and starts a domain name resolution task. When the task is complete, the server returns the resolution result to the client in JSON format.

6.1 Response fields

The response message is in JSON format. The following table describes the meaning of each node in the path.

6.2 Response codes

The code field describes the overall status of the HTTP resolution request response. The following table lists the possible values, their meanings, and the corresponding HTTP status codes.

6.3 No-IP indicator codes

A client might not receive an IP address in the response. This can be due to domain name configuration issues, such as the domain name not being added to the resolution list in the console, or issues with the domain name itself, such as no IPv6 record being configured for it. You can use the no_ip_code field to determine the reason. The following table lists the possible values and their meanings.

6.4 Response examples

Successful response in plaintext mode

• HTTP status code: 200

• Sample response body:

{
    "code": "success",
    "mode": 0,
    "data": {
        "answers": [
            {
                "dn": "www.example1.com",
                "v4": {
                    "ips": [
                        "180.101.XX.XX",
                        "180.101.XX.XX"
                    ],
                    "extra": "simplestring",
                    "ttl": 60
                },
                "v6": {
                    "ips": [],
                    "no_ip_code": "RRNotExist",
                    "extra": "simplestring"
                }
            },
            {
                "dn": "www.example2.com",
                "v4": {
                    "ips": [
                        "180.101.51.73",
                        "180.101.49.44"
                    ],
                    "ttl": 60
                },
                "v6": {
                    "ips": [],
                    "no_ip_code": "RRNotExist"
                }
            }
        ],
        "cip": "192.168.1.1"
    }
}

Successful response in ciphertext mode

• HTTP status code: 200

• Sample response body:

  {
    "mode": 2,
    "code": "success",
    "data": "fCF3fVHFOrNAyCs9cEJAprAYx+RfdM8zDbXmVLypO/8ei1muFJ3cQ7EbyekDAU9CN+5UpnHf7vYQGplfXmuwbcSNz9J6hNVQ8XI+i5OTmZ3kRkTpPM8yXI7P7DYwRfWzpFB0Xu41iFHtv4uFYsRQAbNwnD7q9r2NXAUkBFPOOIJGeije9F9k5l4ytr1PFq/yruzsHXEktCT0wyEsnTSamplHYLnBfqwyKgaBharveZeGGlU1tfF6QE5xY2CRRBjntCnbvkuP8gv4y14qw8VYh3/YD6z3mTk6sgVO1rPc9YI039drDTpYf16WsPb+tPZ5YC805knG5k2OcsnxwNCfj/+ijJQSFBacCPbL5TfIdXfrAw8eczqIQLcTjQ7PExfHSkFxDJgzcl+V6cqI8lbn5vJsQcF2Bedo6WSLUPiy3vgdwOl8x2g7eqXnBzcSNsclQBVRK7g5gwynRBbZGJ4krH8="
  }

Failed response example

• HTTP status code: 4xx/5xx

• Sample response body:

  {
    "code": "MissingArgument"
  }

6.5 Response data decryption (optional)

When the server returns an encrypted response (the mode field is 1 or 2), you need to decrypt the data field to obtain the actual resolution result.

Decryption process

1. Check the encryption mode: Determine the encryption mode from the mode field in the response:

• mode: 1 - AES-CBC mode

• mode: 2 - AES-GCM mode

2. Base64 decode: Base64-decode the data field in the response to obtain binary data.

3. Extract the IV and ciphertext: Extract the IV and ciphertext from the decoded data based on the encryption mode:

• AES-CBC mode (mode=1)

  • The first 16 bytes are the IV.

  • The subsequent bytes are the ciphertext.

• AES-GCM mode (mode=2)

  • The first 12 bytes are the IV.

  • The subsequent bytes are the ciphertext.

4. Perform decryption: Decrypt the ciphertext using the secretKey obtained from the console and the extracted IV.

5. Obtain the decrypted result: The decrypted data is the original content of the data field. You can parse this data according to the response field format.

Response decryption example

• Value of the data field in the response

  hvlBFDr8ZaQjNCyqvyn6cUPs/l/QI6Z8pORPdmpl/MpeslasdMi432cW5mFfPnvHmwzZpmgyd6vCnQb89YeIqwz0Yy61l9pm0PWX41xhD19HoTQPxHp90uLxjGYQIGgV6PPGVu84jyKLsao9tUTgTZc6zJnhZKnfMZjP5G67nRrwoU1r1SR68GJ6WyTL4JAqnHJoDx7yg08GAlrzYmbfiCSemy3/+yDvBZAE2jV692t/JAwtuSOlAHBX30Rx/VMdSsgaFDfQmPr+FNxBlPtcrrS2ml8xgvR/m4Gx8CncsQBZX1FoUHlfrGb4kAXvA0ilfCm5/4pO0fzqXwyE8QoBpwC06NtO5F4imdjQKfPWQByabIXE4SetroeGE0m/p6kt6n6xinbkH0oIcw9i4COibLr9TuOtDI+wN9oMtW9Xpo7rgQbsEDr55ABSr+4YgK2zAEuY13FabmgNMPhZQvBZcEpWEOQ=

• Decrypted plaintext

  {
    "answers": [
      {
        "dn": "www.example1.com",
        "v4": {
          "ips": [
            "192.185.XX.XXX"
          ],
          "ttl": 14400
        },
        "v6": {
          "ips": [],
          "no_ip_code": "RRNotExist",
          "ttl": 600
        }
      },
      {
        "dn": "www.example2.com",
        "v4": {
          "ips": [
            "172.67.XXX.XX",
            "104.21.XX.XX"
          ],
          "ttl": 300
        },
        "v6": {
          "ips": [
            "2606:4700:3037:0:0:0:ac43:c316",
            "2606:4700:3037:0:0:0:6815:2c31"
          ],
          "ttl": 300
        }
      }
    ],
    "cip": "192.168.1.1"
  }

  What to do next

  This topic described how to resolve domain names using the HTTP API. The process includes constructing request parameters, optionally encrypting and signing them, sending the request, and parsing the response. For more information, see Best practices to learn how to implement a stable, secure, and high-performance HTTPDNS client based on the resolution API.