1. 目的

本规范旨在为公司所有对外开放的 API 提供一套统一的设计、开发、管理和维护标准。通过遵循本规范，我们致力于构建清晰、一致、安全、易用且具备良好开发者体验的 API 系统。

2. 适用范围

适用于所有对外提供服务的 HTTP(S) API，包括但不限于提供给外部合作伙伴、第三方开发者或客户端（Web/Mobile）的接口。所有相关开发、测试及运维人员均应遵守本规范。

3. 核心设计原则

  • 用户友好: 接口的设计应首先考虑开发者的使用体验。命名清晰、结构一致、文档完善。
  • 安全可靠: 所有接口必须经过严格的安全设计，防止数据泄露和恶意攻击。
  • 稳定可扩展: 接口应保持向后兼容，并能应对未来的业务增长和变化。
  • 无状态: 服务端不应保存客户端的会话状态。每一次请求都应包含所有必要的信息。

4. 请求路径设计规范

域名规范

  • 建议使用独立域名，避免因服务器更换造成接口不可用。
  • 首选: https://api.xxx.com
  • 备选: https://xxx.com/api

协议

  • 必须使用 HTTPS 协议传输，以保证数据在传输过程中的安全。

版本控制

  • 将 API 版本号放入 URL 中，这是最清晰直观的方式。
  • 示例: https://api.xxx.com/fy/v1

路径命名

  • 统一使用 小写字母。
  • 如果需要分隔单词，使用 连字符 -，避免使用下划线 _。

5. 请求规范

请求头 (Headers)

  • Content-Type: application/json
  • timestamp: 时间戳（防止重放攻击）
  • nonce: 随机数（防止重放攻击）
  • sign: 签名（身份验证与防篡改）

请求体 (Body)

  • 请求的数据必须以 JSON 格式在请求体中传递。
  • JSON 字段命名统一使用 小驼峰命名法 (camelCase)。

请求体示例：

1
2
3
{
  "inputStr": "ᠳᠤᠮᠳᠠᠳᠤᠤᠯᠤᠰ"
}

6. 响应规范

状态码

使用标准的 HTTP 状态码来反映请求结果。

  • 200: 成功
  • 4xx: 客户端错误 (400 参数错误, 401 未认证, 403 无权限, 404 未找到, 429 请求过多等)
  • 5xx: 服务器内部错误 (500 系统错误, 503 服务不可用等)

响应体

  • 统一返回 JSON 格式。
  • 统一响应结构，方便调用方统一处理。

成功响应示例：

1
2
3
4
5
6
7
{
  "code": "0000",
  "message": "Success",
  "data": {
     "country": "中国"
  }
}

错误响应示例：

1
2
3
4
5
{
  "code": "0004",
  "message": "非法请求",
  "data": null
}

7. 文档和错误码

文档

  • 所有 API 必须提供实时、准确的文档。
  • 文档必须包含：接口描述、请求路径、方法、所有参数（路径、查询、请求头、请求体）的详细说明、所有可能的响应（包括成功和失败）示例。

错误码

  • 制定统一的业务错误码体系，方便客户端根据错误码进行相应的逻辑处理。
  • 错误码应具备一定可读性。

8. 安全规范

认证

  • 接口需要经过认证，认证信息通过请求头或者请求体传递。

授权

  • 服务端必须在认证通过后，进一步校验当前用户是否有权操作目标资源。
  • 无权访问时，必须返回非法请求状态码。

签名机制

为防止中间人攻击和参数篡改，接口必须引入请求签名机制。（按照双方约定进行签名，以下是目前信息处理平台的实现方式）

  1. 获取凭证: 获得 AppKey 和 pid，由服务端提供。
  2. 拼接字符串: 将所有必填参数（包括 timestamp, nonce）按 key 字母排序，拼接成 key=value&key=value... 格式的字符串。
  3. 生成签名: 使用 MD5 算法，对拼接后的字符串进行加密，生成签名 sign。
  4. 发送请求: 请求时需要带 timestamp、nonce、sign 及其他必填参数一同发送到服务端。（AppKey 不参与传输，仅用于后端校验或作为盐值，具体视约定而定）。
  5. 服务端校验: 服务端以完全相同的方式生成签名，进行校验。

9. 接口变更与版本升级规范

变更基本原则

向后兼容性是接口变更的最高原则。任何变更都不能导致现有调用方在未修改代码的情况下调用失败。

非破坏性变更

以下变更是允许在当前版本中进行的，因为它们保持了向后兼容：

  • 新增 API 接口。
  • 在请求体中新增可选参数。
  • 在响应体中新增字段。（不能改变原有结构）
  • 修改文档、注释或错误消息文本。

破坏性变更

严禁在现有版本中直接进行任何破坏性变更。以下行为被定义为破坏性变更：

  • 更改或删除现有的接口地址 (URI)。
  • 删除请求参数或响应字段。
  • 重命名请求参数或响应字段。
  • 将现有可选参数变为必选。
  • 更改现有参数或响应字段的数据类型。
  • 更改现有参数的枚举值。
  • 更改认证或授权机制。

版本升级策略

当业务发展必须进行破坏性变更时，必须通过发布新版本 API 的方式进行。

  1. 提升版本号: 在 URI 中增加主版本号，例如从 /fy/v1 升级到 /fy/v2。
  2. 并行运行: 新旧两个版本的 API 必须在一段时间内并行运行，为调用方提供充足的迁移时间。
  3. 提供迁移文档: 必须提供清晰的迁移指南，详细说明新旧版本的差异以及如何从旧版本升级到新版本。

接口弃用策略

当新版本发布后，旧版本应进入弃用流程。

  1. 标记弃用: 在 API 文档中明确标记旧版本为“已弃用”。
  2. 设定废止日期: 设定并公布一个明确的“废止日期”，在此日期之后，旧版本接口将停止服务。
  3. 过渡期: 从“标记弃用”到“废止日期”之间应至少保留 3个月 的过渡期，对于核心重要接口，应适当延长。

10. 沟通与通知

所有接口的变更、版本升级或弃用计划，都必须提前通知所有已知的调用方。