「谷雨解字」开放接口

开放接口以 RESTful API 的形式提供。开发者可以通过开放接口，实现动态创建科学字体，并在自己的网站和小程序中引用。

接口说明

「谷雨解字」提供以下两个接口：

• 解字接口：
  https://guyujiezi.com/api/encrypt
• 授时接口：
  https://guyujiezi.com/api/nonce

解字接口用于创建科学字体，接口返回生成的字体链接，可以在网页中直接引用；授时接口用于获取服务器当前时间戳。

1. 解字接口（https://guyujiezi.com/api/encrypt）

通过 POST 请求调用该接口，请求内容为包含 "plaintext" 和 "shadowtext" 参数的 JSON 对象，即请求 "Content-Type" 头部为 "application/json"，且请求必须包含用于身份验证的 "Authorization" 头部。接口返回一个 JSON 对象，其中包含一组 URL 集合，指向刚才创建的字体文件。

一个典型的调用请求如下：

GET /api/encrypt HTTP/1.1
HOST: guyujiezi.com
Content-Type: application/json
Authorization: GYJZ pk=<public_key>, nonce=<nonce>, sign=<signature>

{
    "plaintext": <plaintext>,
    "shadowtext": <shadowtext>,
    "font": <font_name>,
    "formats": <font_formats>
}

其中：

• public_key
  即应用密钥中的公钥。可以在“个人中心-密钥管理”中找到。
• nonce
  系统当前 UTC 时间戳。客户端的系统时间和服务器系统时间误差不能超过 ±600 秒（10 分钟），否则将认证失败。在调用该接口前，可以用授时接口来修正系统时间。
• signature
  通过公钥、密钥和 nonce 时间戳计算出的签名。算法如下：

  <signature> = hex(sha1(<public_key>:<secret_key>:<nonce>))

• plaintext
  原文字符串。
• shadowtext
  阴书字符串。
• font_name
  字体名称字符串，可选参数。如不设置将使用默认字体。系统支持的字体名称有：
  • 阿里巴巴普惠体 R
  • 懐源ゴシック HW CN Regular
  • Noto Sans CJK SC Regular
  • Noto Sans Mono CJK TC Regular
  • Noto Serif CJK SC
  • 得意黑
  • 思源黑体
  • 思源宋体 CN
  • 站酷高端黑
  • 郑庆科黄油体Regular
• formats
  字体格式数组，可选参数。如不设置将生成所有支持的字体字体格式。默认字体格式数组如下：

  ["woff2", "woff", "eot", "otf/ttf"]

若调用成功，服务器响应 HTTP 状态码 200，并返回如下格式的 JSON 对象：

{
    "woff2": "https://guyujiezi.com/fonts/guyujiezi.woff2",
    "woff": "https://guyujiezi.com/fonts/guyujiezi.woff",
    "ttf": "https://guyujiezi.com/fonts/guyujiezi.ttf",
    "eot": "https://guyujiezi.com/fonts/guyujiezi.eot",
}

返回的字体 URL 可以直接在网页中引用。

若调用失败，服务器响应 HTTP 状态码 4XX，并返回如下格式的 JSON 对象：

{
    "code": <error_code>,
    "name": <error_name>,
    "message": <error_description>,
    "help": <help_url>
}

其中：

• error_code
  整数类型的错误代码。跳转到错误说明。
• error_name
  错误名称字符串。
• error_description
  错误描述字符串。
• help_url
  包含帮助信息的 URL。

2. 授时接口（https://guyujiezi.com/api/nonce）

通过 GET 请求调用该接口。接口返回一个 JSON 对象，其中包含服务器当前的时间戳。调用该接口不需要身份认证。

一个典型的调用请求如下：

GET /api/nonce HTTP/1.1
HOST: guyujiezi.com

若调用成功，服务器返回如下格式的 JSON 对象：

{
    "nonce": 1553232323
}

错误说明

0x01. ARGUMENT_CONFLICT

参数冲突。对于某些重载的接口，请求携带了一些不必要的参数。请确保提交的参数是正确的。

0x02. MISSING_ARGUMENT

缺少参数。请求的 JSON 对象中缺少必要的参数。除了可选的参数，其他参数都是必要的。请确保提交的参数是正确的。

0x03. INVALID_REQUEST

非法请求。服务器无法解析请求中的 JSON 内容，可能是请求内容的格式不正确造成的。请确保请求内容是标准的 JSON 格式。

0x04. SERVICE_ERROR

服务出错。调用请求是正确的，但是服务器发生了一些问题导致无法生成正确的结果。请稍后再试。

0x05. INVALID_ARGUMENT

非法参数类型。接口收到了非期望的参数类型。请确保提交的参数是正确的。

0x06. UNEXPECTED_VALUE

非期望值。接口收到了非期望的参数值。请确保提交的参数是正确的。

0x07. UNAUTHORIZED

身份未认证。没有通过接口身份认证。可能是应用密钥失效，或者应用密钥所属的用户被屏蔽。请确保请求包含了正确的 "Authorization" 头部。

多语言开发包

• PHP
• Python
• Javascript (Node.js)