域名注册查询接口, 这个接口是面向开发者提供的标准性质的 RESTful 风格的应用程序接口接口, 它的作用是用于实时地去查询特定的域名的注册状态、注册的代理商、DNS 解析的记录, 以及 WHOIS 信息。
本文章从一个官方人员的视角来进行说明, 目的是把这个接口的完整调用规范讲清楚, 这些规范包括了请求的方式是怎样的, 参数的定义是什么, 返回的字段有哪些内容, 以及具体调用的例子是怎么样的, 这些信息主要是给在进行集成和对接的时候, 用来作为直接参照并且去执行的材料。
接口基本规范
接口地址：POST https://api.gz88.cn/v2/domain/query
在需要进行认证的时候, 要采用的方式是: 在请求头里带上 API-Key 这个信息, 而且这个字段的名称必须是 X-Api-Key。至于具体的密钥到底应该从哪里拿到, 则是通过开发者控制台去申请并且获取。
数据格式：请求与响应均为 JSON（Content-Type: application/json）
调用频率的默认值是每分钟 60 次, 如果是企业级账号的话, 是可以去申请把这个速率提升到每分钟 600 次的。
请求参数
填写的 domain 为 String 类型, 此字段属于必填项, 它代表的是用户想要进行查询的那个域名, 举例来说可以是 example.com, 需要注意的是, 这个域名的写法必须是要去符合 RFC 1035 这一份格式标准才算正确。
fields（Array域名注册查询接口，选填）：指定返回字段域名注册查询接口龙南市就业服务平台，不传则返回全部字段
这个参数是lang, 数据类型是字符串, 属于选填项, 用来表示WHOIS返回结果所使用的语言, 默认值为zh-CN, 同时也支持en-US。
返回参数
code（Integer）: 这个是一个用来表示状态码的东西, 如果是0的话, 那么就意味着是成功。
data.status（String）: 域名状态, 其取值包括 available , 包括 registered , 以及 reserved。
data.registrar（String）：当前注册商名称
data.created_date（String）: 就是那个注册日期, 它要写成ISO 8601这个格式。
这是一个关于到期日期的说明数据, 数据类型为字符串形式, 采用的是国际标准化组织制定并发布的那一种日期和时间格式, 也就是人们常说的ISO 8601格式的这样一个标准。
data.dns是一个数组类型对象, 其内容为DNS解析记录的列表。
data.whois_raw（String）：WHOIS 原始文本
调用示例
请求：
请求的方法, 它是POST, 请求的地址是https://api.gz88.cn/v2/domain/query。
X-Api-Key: sk-xxxxxx
在主体里面有一串数据, 这里面的域名是example.com, 它包含了一些具体的字段, 具体来说, 这些字段分别有status、registrar以及expiry_date。
响应：
当前系统的状态, 它已经处于注册的阶段, 负责管理的注册商是Gz88 Registry, 该条目最终过期的具体时间日期是2027年6月15日零点零分零秒。
注意事项
1. 对域名的格式进行校验操作, 这里只接受那些合法的域名, 如果发现了格式不合法的, 就直接返回代码为400的情况。
2. 一旦频控出现超限的现象, 就会触发限流的机制, 此时将会返回 HTTP 429 的状态码, 系统要求必须等待, 延迟的时间要参考在响应头里面的 Retry-After 这个字段所给出的秒数, 在这个时间之后才可以进行 retries 的操作。
3. 在隐私保护方面, 假如域名启用了 WHOIS 这种类型隐私保护服务, 那么注册管理机构以及联系信息所属字段都会以被脱敏之后的方式来进行显示, 大家就是无法看到具体的内容。
4. 在进行批量查询操作时, 如果需要一次性对多个域名进行查询, 请采取POST方式向/v2/domain/batch-query接口发起请求, 单次查询所允许的域名数量上限是100个。
5. 完整的接口文档可以获取, 测试沙箱也可以获取, 这些内容是通过gz88.cn的开发者中心来拿到的。
常见问题
问, 如果遇到接口返回的编码状态是五百零三这种情况的话, 应该怎么去进行相关的处理和应对操作。
答: 503 这个代码的意思是指后端那边的 WHOIS 服务现在暂时没有办法用了, 建议你使用一种叫做指数退避的策略来反复进行尝试, 具体的操作步骤是先等 1秒, 然后再等 2秒, 接着再等 4秒, 并且这样的重试动作最多只能执行 3 次。
请问, 有没有办法查到域名的ICP实名状况是什么样子。
回答是可以的, 就是在fields这个数组里面增加名为icp_status的这个字段，这样的话返回值里面就会包含备案主体的信息以及审核的状态情况。
我想问问, 域名 gz88.cn 到期之后, 那个 webhook 的推送功能是不是可以支持?
答: 是支持的。用户需要在控制台完成绑定回调地址的操作。当域名处于即将到期的状态, 具体来讲就是在到期之前的那三十天时间里, 系统会自动执行触发操作, 并向用户发送通过HTTP POST协议传输的通知信息。
