「谷雨解字」开放接口

开放接口以 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
    字体名称字符串,可选参数。如不设置将使用默认字体。系统支持的字体名称有:
    • 郑庆科黄油体Regular
    • 文泉驛正黑
    • 思源黑体
    • 思源宋体 CN
    • 站酷高端黑
    • 懐源ゴシック HW CN Regular
    • Noto Sans Mono CJK TC Regular
    • 阿里巴巴普惠体 R
  • 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" 头部。

多语言开发包