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 resolution API supports single and batch domain name resolution, with optional signing and encryption. The general workflow 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.

The following sections cover the HTTP API request and response specifications, including parameter definitions, encryption and signing rules, and the response structure:

• 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

Request parameters define the resolution task and control encryption and signing. You can combine parameters for plaintext or ciphertext mode, signed or unsigned requests, and single or batch domain name resolution.

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 resolution API supports encrypting the dn, cip, q, and sdns-* parameters to protect request confidentiality even in non-HTTPS environments. Follow these steps 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)

Request signing enhances identity authentication and prevents unauthorized use. This section explains how to calculate the signature parameter s and construct a signed request, ensuring that resolution requests are verifiable and tamper-proof.

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

The server processes a valid resolution request and returns the result 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 response may not contain an IP address if, for example, the domain name was not added to the resolution list in the console or has no matching DNS record. Use the no_ip_code field to identify the cause.

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

  After you understand the resolution API, see Best practices to learn how to build a stable, secure, and high-performance HTTPDNS client.