API 与集成
Optifora API 如何运作
本页说明 API 的整体形态：如何证明身份、版本如何演进、请求要遵守哪些限额、错误长什么样，以及如何与外部交换数据。
产品仍在开发中，API 接口面尚未完全定型。各接口的参考文档将另行发布；本页不提供地址，也不提供示例调用，只讲机制。
身份认证
每一次请求要么属于某个人，要么属于某个已注册的应用。没有身份的请求到达受保护接口时，会以未认证返回。
- Bearer 令牌访问令牌放在请求的授权标头中传递。它经过签名，只说明这次请求属于谁。
- 有效期很短访问令牌在以分钟计的时长后失效；具体时长是部署设置项，默认为三十分钟。
- 刷新与轮换会话通过刷新令牌续期，每次续期都会签发一对新令牌。若已用过的刷新令牌被再次提交，该用户的所有会话都会被撤销。
- 权限不写死在令牌里令牌只携带身份；某人能看到什么，每次请求都要向数据库确认。因此被收回的权限会在手上的令牌过期之前就失效。
- 集成方密钥已注册的应用使用自己的密钥接入。明文值只在创建时显示一次；系统保存的是它的摘要，以及可用于识别密钥的非机密前缀。
- 由机构授予访问权无论一个应用被多少人使用，只要机构没有记录授权，它就一行数据也看不到。授权有日期、有范围，并且可以撤销。
版本管理
- 版本写在路径里接口发布在版本前缀之下；当前接口面为第 1 版。
- 破坏性变更另开路径已有接口的约定不会就地改动。不兼容的变更发布在新的版本路径上，旧路径继续可用。
- 文档标明自身版本参考文档会标明自己是从哪个版本生成的；您读的是哪个版本，文档自己会回答。
运行环境与限额
参考文档声明两套环境：生产环境与本地开发环境。根地址随密钥一并交给集成方，不在本页公开。
- 存活与就绪分别度量一个接口说明进程是否存活；第二个接口会向数据库发出真实查询，确认数据库可达。只有第二个接口才决定是否应把流量导过来。
- 浏览器来源限定在名单内跨源请求只接受事先声明的来源；在名单为空时，浏览器发起的跨源请求一律拒绝。
- 请求体上限请求体不得超过五兆字节。大批量数据以带有独立状态记录的批量传输任务发送，而不是塞进一次请求。
- 机密不写入日志服务器日志不记录授权标头、Cookie、密码，也不记录身份证件号码。
速率限制
限额按地址、按分钟计算。默认每分钟 120 次请求，可在部署时设定。剩余额度会在每次响应的标头中给出。
| 响应标头 | 说明的内容 |
|---|---|
| x-ratelimit-limit | 时间窗内的总额度。 |
| x-ratelimit-remaining | 本时间窗内还剩多少额度。 |
| x-ratelimit-reset | 额度重置前还有多少秒。 |
| retry-after | 重试前需等待的秒数。仅出现在拒绝该请求的响应中。 |
一旦超出限额，请求会被拒绝，响应会以秒为单位说明需要等待多久。重试应在该时间之后进行，而不是立即重试。
错误格式
所有错误都用同一个信封返回：一个供机器判断的短代码字段，一个供人阅读的说明字段。
- error供客户端据以分支处理的短代码。
- message对所发生情况的说明。
| 状态 | 代码字段 | 含义 |
|---|---|---|
| 400 | Bad Request | 请求与结构定义不符。说明中会指出缺失或无效的字段。 |
| 401 | unauthenticated | 没有有效身份：未发送令牌、令牌已过期，或者验证未通过。 |
| 404 | Not Found | 没有这个接口，或者没有这条记录。 |
| 429 | Too Many Requests | 超出速率限制；响应会说明需要等待多久。 |
| 5xx | internal_error | 意外故障。细节不会交给客户端，而是写入服务器日志。 |
分页
返回列表的接口都接受同样的两个参数、返回同样的计数字段，因此分页逻辑不必为每个接口重写一遍。
- limit一页应包含多少条记录。最少 1 条，最多 200 条；未设定时为 50 条。
- offset跳过多少条记录。从 0 开始。
- total符合筛选条件的记录共有多少条。
- count本次响应实际返回了多少条记录。
响应还会回显它所使用的 limit 与 offset；客户端从答复中读取自己的位置，而不是靠猜。
数据交换与 Webhook
交换方式是一项设置，而不是另一款产品：每个已注册应用都在自己的记录上带着它所采用的方式。
| 方式 | 含义 |
|---|---|
| 单向——向外 | Optifora 发布数据；对方读取数据或订阅事件。 |
| 单向——向内 | 对方推送数据；Optifora 校验后写入。 |
| 双向 | 双方都写入；冲突规则事先约定。 |
| 握手 | 每次传输都会建立一次会话：发起、校验、批准、传输、回执。回执双方各留一份。 |
- 事件主动推送Webhook 会把事件推送到已注册应用声明的回调地址。无法送达的事件留在队列中重试，绝不会被悄悄丢弃。
- 同一请求不会写入两次写入请求会带一个幂等键。使用相同键的第二次请求不会再创建一条记录。
- 每一次调用都被度量谁在什么时候、以什么范围、得到什么结果调用了接口，全部记录在案。同一份记录既回答排错问题，也回答“这份数据是谁取走的”。
- 我们自己的应用走同一道门不存在享有特权的第二条通道。我们自己的集成，就是外部开发者所面对的接口面的证明。
交换层的数据模型已经就位，接口尚未发布。发布后，本节会链接到参考文档中的对应条目。
参考文档
参考文档不是手写的，而是由接口的结构定义生成。每个接口交出结构定义后，文档自动补全，因此文档与实际行为不会脱节。
- 当前状态：编制中结构定义正按模块逐个推进。文档发布之前，每个接口的请求与响应都会在其中呈现。
- 将发布两种格式一份机器可读的 OpenAPI 文档，以及一份由同一文档生成、可在浏览器中查阅的参考页面。
- 访问分层概览面向所有人开放。完整参考文档可能置于文档令牌之后，只发给已注册的集成方；至于生产密钥与回调地址，根本不属于文档范畴——它们属于应用注册记录。
- 地址规范将发布两份参考文档，地址固定：client-api.optifora.com/docs 对外开放，admin-api.optifora.com/docs 需要授权且不对外。两者目前均未上线；上线后会在本节补上链接。
如果您的集成方案已经明确，请通过联系页面告诉我们：接口开放时，您会是最先收到通知的一批。