该API域名验证接口（Domain Verification API）, 它的用途是通过程序化的方式, 来核验指定域名的DNS解析记录、WHOIS注册状态以及SSL证书的有效性。

这个接口是由 gname.xin 平台对外提供的。它支持批量查询功能。在单次请求里面, 最多可以传入50个域名。它的响应时间通常是不超过800ms的。

01接口地址与请求方式

接口地址：POST https://api.gname.xin/v1/domain/verify

请求格式：Content-Type: application/json

进行鉴权的时候, 需要你在请求头里面携带上这样一个信息, 也就是Authorization这一栏的后面写上Bearer, 再写上你的API_KEY。

这个API_KEY是由平台管理后台里面的开发者中心生成的, 当发现有密钥泄露的时候, 必须要在后台立即吊销它并且重新生成一份新的。

02请求参数

参数名 类型 必填 说明
domains string[] 是 待验证域名数组API域名验证接口API域名验证接口，最多50个，示例：["gname.xin","example.com"]
check_types string[] 否 验证维度，可选值：dns、whois、ssl；不传则默认全部执行
timeout_ms int 否 单域名超时阈值，默认5000ms，最大15000ms

03返回参数

返回的数据是JSON格式的数组, 其中的每一个对象都用来展示与某一个特定域名相关的验证完成之后的具体结果情况。

[
  {
    "domain": "gname.xin",
    "dns": {"status": "ok", "a_records": ["203.0.113.10"], "ns": ["ns1.gname.xin"]},
    "whois": {"status": "active", "registrar": "GName Inc", "created": "2019-03-15"},
    "ssl": {"status": "valid", "issuer": "Let's Encrypt", "expire": "2026-02-01"},
    "code": 0,
    "message": "all checks passed"
  }
]

code: 0 表示全部通过, 1 表示部分维度异常, 2 表示域名不存在或已释放。

各个维度里的 status 这个字段, 它的取值可以是这些情况中的一个, 具体来说, 就是 ok , 或者 warning , 再或者是 error , 还有可能是 not_found , 大家要注意看清楚。

04调用示例

curl -X POST https://api.gname.xin/v1/domain/verify \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "domains": ["gname.xin", "test-domain.cn"],
    "check_types": ["dns", "ssl"]
  }'

05频率限制与配额

API域名验证接口：调用参数与返回结果全解(图1)

针对单密钥的情况, 其常规的每秒查询数配额被设定为一十这个数值。在出现流量突发状态的时候, 它的上限能够撑到五十这个数值。一旦超过了之前所提到的这些限制条件, 系统会给您返回一个带有html标签的提示信息, 具体内容是四个二十九表示太多的请求这个状态码。

每天提供的免费调用次数是5000次, 如果使用了超过这个数量, 那么多出来的部分是要按照每次0.002元的标准来收费的。想要看到自己的账单详情, 可以到 gname.xin 控制台里的「用量中心」去查看。

06常见异常处理

邢台市重点项目建设促进中心

错误码 含义 处理建议
401 API_KEY无效或已过期 重新生成密钥
403 该密钥无域名验证权限 在后台为密钥添加scope
422 domains数组为空或超50个 拆分批次调用
429 触发QPS限制 客户端加入指数退避重试
500 服务内部异常 携带response中的trace_id联系平台支持

07注意事项

1. 用户需要在域名列表里面填入的数值, 应当全都采用小写的形式, 并且不能加上任何协议的前缀部分, 这种格式被叫做裸域名, 大家可以参考 gname.xin 这个例子作为参照。

如果填写的信息中包含了像 http:// 这样的协议前缀, 又或者使用了大写字母, 那么系统将会返回状态码为 422 的结果。

2. 由于WHOIS验证这个环节会受到上游注册局那边给出的响应情况的影响, 所以偶尔出现的延迟就属于正常的现象, timeout_ms 这个参数可以适当调大一点。

3. 这个接口在返回信息的时候, 里面的SSL相关信息只是代表了那个时间点的一种状况, 我们并不建议大家把它当成唯一的监控手段来用, 最好是能够结合着定时轮询这种方式一起去做。

4. 所有的请求以及响应都通过了HTTPS的方式进行传输, 明文接口已经下线了, 旧的HTTP端点要在2026年6月30日这一天彻底被关闭。

以上就是关于gname.xin这个域名的验证接口的一套完整的调用规则的情况。如果您有需要使用那个沙箱环境来做调试的话, 那就能够在控制台上把那测试密钥给开通起来。那么因为这个测试里面的相关数据会在每一天的凌晨零点进行重置操作, 所以它是不会影响到生产的那些配额的。