域名注册API接口是一种面向开发者和企业的、标准化的程序化的服务形式。它支持通过API自动完成域名注册、可用性查询、续费以及转移等全生命周期内的操作环节。

在完成接入之后, 业务系统可以在完全不需要人工进行干预的前提条件下, 大规模地批量处理域名相关的交易活动。这篇文章是基于ICANN注册局规范来进行撰写的。该文章将详细说明域名注册API接口的完整接入路径的具体内容情况。

接入前置条件

在你去调用那个叫域名注册API这样的接口之前, 你必须要先完成下面的那些准备工作。

你得去拿到那个被ICANN给认证过的注册商的资质, 或者是要拥有那种由上级授权代理而来的协议才行。

你需要进入管理后台去办理那个API密钥的事情, 然后把Access Key还有Secret Key这两个东西拿到手里。

服务器已经启用了HTTPS这一功能, 并且该功能的协议版本为TLS 1.2或者比TLS 1.2更新的版本, 同时, 所有的接口仅支持通过加密通道来进行数据传输。

域名注册API接口怎么接入?调用流程、参数与示例全解析(图1)

准备好那些用来做实名认证的材料, 这些材料里面包括企业的营业执照, 还有法人的身份证明之类的东西。

核心接口端点

域名注册API接口会包括一些核心的东西, 这些东西呢, 就是以下这些端点:

端点 功能 说明
/v1/domains/register 注册域名 支持.com、.cn、.com.cn等后缀
/v1/domains/check 查询可用性 单次最多批量查询100个域名
/v1/domains/renew 续费 支持1至10年
/v1/domains/transfer 域名转移 含转出与转入
/v1/domains/query 状态查询 含DNS记录、注册信息

在系统设计时统一采用RESTful风格, 其中请求方法采用GET和POST这两种方式, 而响应格式则统一为JSON。

调用流程

1. 构造出一个请求头, 在这个请求头里面携带着那个叫做Authorization的东西, 这个东西的具体内容是Bering这个类型的Token。然后再把这个叫作X-API-Key的内容加进去。最后还要加上Content-Type这一项, 把它的值设成application/json这个样子。

2. 进行签名验证的时候, 大家需要使用Secret Key来对请求体执行HMAC-SHA256这样的签名操作, 接着就要把运算得到的结果写入到X-Signature这个字段里面去。

域名注册API接口怎么接入?调用流程、参数与示例全解析(图2)

3. 发送请求, 就是去通过 HTTPS POST 来调用对应的端点。

4. 当HTTP状态码等于200的时候, 就表示成功啦, 这个时候响应的内容里面会包含订单号还有域名的状态。如果状态码不是200, 那就按照错误码来处理, 并且进行重试操作。

关键请求参数(以/v1/domains/register为例)

参数 类型 必填 说明
domain string 是 完整域名,如example.com
period int 是 注册年限域名注册API接口,取值1-10
ns array 否 自定义NS域名注册API接口,缺省使用系统默认NS
reg_contact object 是 注册联系人(姓名、邮箱、电话、地址)
auto_renew bool 否 是否开启自动续费,默认false

调用示例

请求:

POST /v1/domains/register
{
  "domain": "example.com",
  "period": 1,
  "reg_contact": {
    "name": "张三",
    "email": "zhangsan@example.com",
    "phone": "+86-138-0000-0000"
  },
  "auto_renew": true
}

成功响应:

{
  "code": 200,
  "order_id": "DR202611170001",
  "domain": "example.com",
  "status": "registered",
  "expire_date": "2027-11-17"
}

注意事项

大城新闻网

域名注册API接口怎么接入?调用流程、参数与示例全解析(图3)

限流规则是这样规定的, 针对单个Access Key它的默认QPS是被设置成10的, 当次数超过这个上限之后就会返回一个HTTP 429的状态码, 客户端需要采用的方式是使用指数退避来进行重新请求。

这个保护期, 是指当域名注册成功以后, 会进入到一个长达30天的删除保护期, 在这个期间, 该域名是不可以办理转出手续的, 同时也是不可以被删除的。

那些带有.cn等后缀的域名, 必须要去提交ICP备案的信息, 没有完成备案工作的域名, 就没法儿把解析给做完。

API密钥这种东西, 是绝对不可以用硬编码的方式来处理。我们建议的是, 要通过环境变量或者那些专门的密钥管理services来执行注入操作。这样做的目的就是为了降低因为泄露而可能带来的风险问题。