How to use the service IP scheduling API - HTTPDNS - Alibaba Cloud Documentation Center

1. Introduction

The scheduling API is a core component of the HTTPDNS high availability (HA) architecture. It intelligently allocates the best resolution service nodes based on a client's location and network conditions. Use the scheduling API to obtain a list of nearby, healthy service IP addresses for high-performance domain name resolution.

This topic describes how to use the scheduling API, including its format, parameters, security mechanisms, and response handling. The main sections are:

API format: Describes the basic format of the scheduling API and how to construct the URL.
Parameter description: Details the parameters for the scheduling API, including required and optional parameters.
Request signing: Explains the request signing mechanism to improve the security of scheduling requests.
API response description: Describes the API response format and error handling mechanism.
Service IP update mechanism: Provides service IP update strategies and best practices.

2. API format

The scheduling API supports access over HTTP or HTTPS. The API format is as follows:

Service URL: http(s)://{startup_endpoint}/{account_id}/ss? + {request_parameters}
Request method: GET

Note

If you use the HTTPS protocol, you must manually set the `Host` for certificate validation to `resolvers.httpdns.aliyuncs.com`.
{startup_endpoint}: The startup endpoint. For more information and to select an appropriate access point, see the Launch Access Point document.
{account_id} is your account ID. You can obtain it from Developer configuration.
{request_parameters} provides additional scheduling controls. For more information, see the Parameter description section.

3. Parameter description

Use request parameters to control scheduling policies and security mechanisms. You can set these parameters to enable features such as basic scheduling and signature authentication.

3.1. Parameter list

Parameter	Description	Required	Signed	Example value
`account_id`	Account ID. Specified in the URL path.	Yes	No	`100000`
`region`	Scheduling region. Specifies the geographic location of the service cluster. • cn: Chinese mainland cluster (default) • hk: Hong Kong (China) cluster • sg: Singapore cluster • us: US cluster • de: Germany cluster • global: Global proximity-based scheduling	No	No	`cn`
`n`	Random number for the signature. A hexadecimal string with a length of 8 to 16 characters.	No	Yes	`abcdef2345`
`t`	Timestamp for signature validity. It is the current time plus the validity period in seconds. A validity period of 30 to 300 seconds is recommended.	No	Yes	`1632912372`
`s`	HMAC-MD5 signature. A 32-digit hexadecimal string.	No	No	`de7be63a9f19cf11e9d455d7d4f23cb4`

3.2. Request parameter examples

Request for a specific region

GET https://{startup_endpoint}/{account_id}/ss?region=cn&n=abcdef2345&t=1632912372&s=de7be63a9f19cf11e9d455d7d4f23cb4 HTTP/1.1

Proximity-based request

GET https://{startup_endpoint}/{account_id}/ss?region=global&n=abcdef2345&t=1632912372&s=de7be63a9f19cf11e9d455d7d4f23cb4 HTTP/1.1

4. Request signing (optional)

Enable request signing to improve the security of scheduling requests. This mechanism prevents request tampering.

4.1. Signature algorithm

Algorithm: HMAC-MD5
Key: The signing key. You can obtain the key from Developer Configurations.
Input: A string constructed in the `{n}-{secret}-{t}` format.
Output: A 32-digit, lowercase hexadecimal string.

4.2. Signing steps

Generate a random number n: A hexadecimal string that is 8 to 16 digits long.
Obtain a valid timestamp t: The current time plus the validity period in seconds. A validity period of 30 to 300 seconds is recommended.
Construct the signature string: Concatenate the components in the {n}-{secret}-{t} format.
Calculate the signature: Use the HMAC-MD5 algorithm to calculate the signature value.

4.3. Signing example

Assume the following:

Random number n = abcdef2345
SecretKey = 123456
Timestamp t = 1632912372
Region region = cn

Signature calculation process:

String to sign = "abcdef2345-123456-1632912372"
s = HMAC-MD5("123456", "abcdef2345-123456-1632912372")
  = "de7be63a9f19cf11e9d455d7d4f23cb4"

Final request:

GET https://{startup_endpoint}/{account_id}/ss?region=cn&n=abcdef2345&t=1632912372&s=de7be63a9f19cf11e9d455d7d4f23cb4 HTTP/1.1

5. API response description

The scheduling API response contains a list of service IP addresses and related metadata. This section describes the data structure for successful responses, field definitions, and how to handle errors.

5.1. Response format

If the request is successful, the HTTP response status code is 200. The response is in JSON format:

{
  "service_ip": [
    "203.107.1.xx",
    "106.xxx.1.xx"
  ],
  "service_ipv6": [
    "64:ff9b::xxx:121",
    "64:ff9b::xxx:122"
  ]
}

5.2. Response field description

Field	Description
service_ip	List of IPv4 endpoints for the resolution service.
service_ipv6	List of IPv6 endpoints for the resolution service.

5.3. Error responses

If the request fails, the HTTP response status code is 4xx or 5xx. The response is in JSON format:

{
  "code": "MissingArgument"
}

Common error codes:

Error code	HTTP status code	Description
MissingArgument	400	A required parameter is missing.
TimeOutOfSync	400	The time drift is too large. Calibrate the time based on the `Date` response header.
InvalidNonce	400	The random number format is invalid.
InvalidTimestamp	403	The timestamp format is invalid.
AccountNotExists	403	The account does not exist or is disabled.
InternalError	500	An internal server error occurred.

6. Summary

This topic describes the usage and technical details of the HTTPDNS scheduling service API, including key aspects such as the API format, parameter settings, security mechanisms, and response handling. You can use the scheduling API to obtain a list of optimal resolution service IPs. After you obtain the list of IPs, you can perform domain name resolution. For more information, see Domain Name Resolution Interface.