# 公共接口概述

最后更新日期：2023年9月5日

# 提示

如果需要用于 ACME DNS-01 验证（例如 Let's encrypt 证书签发），请使用 PowerDNS 模拟接口，不需要自己对接 API。

# 接口细节

# 接口 URL

https://api.hostker.net/v2

# 请求方法

POST

# 请求和返回内容格式

JSON

# 签名方法

「个人资料」界面获得接口密钥，使用 HMAC-SHA256 算法用密钥对 JSON 内容进行签名。签名结果放在 HTTP 头部的 Sign 字段并在提交时请求。

// PHP 示例
$secret = 'xxxxxxxxxxx'; //密钥
$body = '{action: "DomainDNS.getDomainList"}'; //请求内容
$sign = hash_hmac('SHA256', $body, $secret); //签名结果

// Go 示例
package main
import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
)
func main() {
    secret := "xxxxxxxxxxx"
    body := "{action: \"DomainDNS.getDomainList\"}"
    h := hmac.New(sha256.New, []byte(secret))
    h.Write([]byte(body))
    sign := hex.EncodeToString(h.Sum(nil)) //签名结果
}

// NodeJS 示例
var secret = "xxxxxxxxxxx";
var body = "{action: \"DomainDNS.getDomainList\"}";
var crypto = require('crypto');
var hmac = crypto.createHmac('sha256', secret);
data = hmac.update(body);
sign = data.digest('hex'); //签名结果

# Python3 示例
import hashlib
import hmac
secret = 'xxxxxxxxxxx'
body = '{action: "DomainDNS.getDomainList"}'
sign = hmac.new(
    key=secret.encode('utf-8'),
    msg=body.encode('utf-8'),
    digestmod=hashlib.sha256
).hexdigest()

# 通信规范

# 请求 HTTP 头部字段

字段名	字段值(示例)	类型	说明
Email	xxx@example.com	String	账号邮箱
Sign	xxxxxxxxxxxxx	String	HMAC-SHA256 签名

# JSON 格式

通用参数

字段名	字段值(示例)	类型	说明
action	DomainDNS.createRecord	String	接口方法名称
host	www	String	（根据接口内容决定）
...	...	...	（根据接口内容决定）

示例

{action: "DomainDNS.createRecord", host: "www", ...}

# 统一返回内容

成功返回

字段名	字段值(示例)	类型	说明
success	true	Boolean	是否成功
result	{id: 123}	Object	调用成功后返回的内容，为空时是 {}

成功示例

{success: true, result: {id: 123}}

失败返回

字段名	字段值(示例)	类型	说明
success	false	Boolean	是否成功
error	接口参数错误	String	UTF8 编码的中文错误信息

失败示例

{success: false, error: "接口参数错误"}

# 频次限制

每个 IP 5 分钟内鉴权失败大于 10 次将会禁止访问。IPv6 同一个 /64 子网视为同一个 IP。
每个 IP 1 小时内累计请求次数不能超过 1000 次。
每个用户 5 分钟内接口调用次数不能超过 100 次。
每个用户 1 小时内接口调用次数不能超过 500 次。

超出频率限制将会在限制时间后恢复访问。

# SDK 和第三方服务

感谢敖天羽提供的 Go SDK 封装和 DDNS 服务！

Go SDK：https://github.com/csvwolf/ker.go (opens new window)

DDNS 服务：https://github.com/csvwolf/hostker-ddns (opens new window)

PowerDNS 模拟接口 →