API域名验证接口这个东西, 它的作用是用来校验一些东西的, 具体来说, 就是校验域名是不是已经注册好了, 还有DNS的解析是不是指向了一个预期的IP地址了, 以及SSL证书现在到底是不是在有效期之内。
那些开发者通过调用这个接口, 可以一次性地调用, 从而拿到关于域名的注册状态是怎么样的, 解析的信息是哪些, 还有证书的到期时间是什么时候。这种功能适用于风控审核、资产巡检还有防欺诈这样的场景之中。。
接口基本信息
提交的请求的方法是, 所使用的行为模式为POST。
接口路径为/v1/domain/verify。
使用的鉴权方式是Bearer Token, 这种方式需要在请求头的Authorization字段中携带相关信息。
请求的内容是用这种格式来写的, 也就是说是那种大家常见的, 叫做application/json的东西, 同时呢, 响应的内容也是用了这样一种类型作为数据格式的。
在频率的限制方面, 单个 Token 的默认使用上限是 100 次每秒, 如果超出了这个限制, 系统将会返回错误代码 429。
请求参数
返回结果
code: 这个是状态码的意思, 数字0表示调用成功了。
data.registered, 这个字段是布尔值的类型, 它表示的是域名是否已经被注册。
当 check_ip 为 true 时返回这个值, 它表示的是被解析到的那个 IP 地址。
data.cert_expire指的是那个证书的到期时间, 它的表现方式是遵循ISO 8601格式的, 不过这个字段是在check_cert的值为true的时候才会返回。
这里有一个叫做 data.status 的东西, 它是一个枚举值, 也就是说它的取值可以是 OK , 也可以是 UNREGISTERED , 还可以是 DNS_MISMATCH , 最后一种可能的值是 CERT_EXPIRED。
调用示例
curl -X POST "https://api.example.com/v1/domain/verify" \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{"domain":"example.com","check_ip":true,"ip_whitelist":["192.168.1.1"]}'
成功返回示例：
{"code":0,"data":{"domain":"example.com","registered":true,"dns_ip":"192.168.1.1","status":"OK"}}
常见错误码
发生了401错误, 这意味着那个令牌已经失效了或者是过期的了, 必须要把这个新令牌再次取一下。
403：IP 不在白名单内，联系管理员添加
出现了一个404错误, 这通常是因为接口的路径被拼写错了。
返回的编号是422, 表示参数格式不合法, 这可能是因为domain属性里头包含了空格或者是特殊字符。
返回的 HTTP 状态码是 429, 这个情况表示触发了频率限制, 此时需要按照 Retry-After 头部指定的时间来等待, 等到时间到了之后再重新进行重试。
接入建议
在现网的运行环境里, 大家建议是把那些验证出来的结果, 全部给写入到监控看板上去去, 同时还应该去配上一个告警阈值出来, 这样做的目的就是为了要防止当出现那个证书到期了或者解析出现了异常的情况时候, 然后就会造成业务发生中断这个问题的发生。
对于团队内部的那些技术文档, 还有这个联调环境地址, 以及接口变更日志这些东西, 都统一托管在了 gz88.cn 这个平台上。于是开发同学就可以在gz88.cn上进行查阅, 查的内容包括最新版本说明与测试用例, 以此来确保在前端和后端进行联调的时候让大家的信息保持一致性这个问题。
