首先，请务必记住 API 设计和使用的一个重要法则 Postel's Law(又称作稳健性原则):
- Be liberal in what you accept, be conservative in what you send
下面是关于 API 设计的一些基本问题
API First
将 API 视作产品，并向产品开发一样设计和维护 API
- 在代码实现前的 Design 阶段，就优先定义符合标准规范的 API
- 与客户(API 的使用者)一起设计和审查 API
- 设计可用性、可读性和可维护性的 API
- 长期积极维护 API 并保持 API 的一致性
代码结构
项目(Git Repo) 中应包含以下目录用于描述 API
- README.MD
- 可以包含服务 API Spec 的 Jira Link
- 文档
- 在
doc/*目录下的 markdown 文件或链接到 git
- 在
- 接口定义
- 按 API 版本分目录
v[0-9]*/* - 每个版本中需包含 swagger yaml 文件
- 按 API 版本分目录
安全
无论是 public API 还是 internal API，在设计时都需要考虑安全性问题。对于外部 API，暴露在因特网上本来就充满了风险。对于内部 API，不要认为内网是安全的，比如在微服务网络中，要避免级联失败或者第三方继承点问题。可以采用以下方案提高 API 的可用性：
- 总是使用 SSL(Public API 必须开启，内部 API 根据具体场景具体分析)
- Public API 必须支持 CSRF
- Is your Web API susceptible to a CSRF exploit?
- Throttling
- 主要针对 public API， 此外 internal API 也需要考虑承载能力
- 响应 503 with Retry-After header
- 考虑 Subtle Denial of Service
- DoS attacks：Slowloris, Billion laughs, and ReDoS
- Authentication
- 针对 Public API 使用 Oauth2 或者 HTTP Basic Authentication
- 针对内部 API 可以使用协商的加密认证算法
命名规范
- 总是使用小驼峰
- 使用美式英语
- 允许使用缩写
- 产品名
- API
- config (configuration)
- id (identifier)
- spec (specification)
- stats (statistics)
- 使用准确描述 API 的命名，而非笼统模糊的命名(如 items)
- 尽量避免使用编程语言中的保留字
文档
遵循 OpenAPI Spec version 3，使用 swagger-editor 编辑文档，每个 API 的描述至少包含以下内容：
- x-api-id: 为每个 API 设置 UUID 以便于索引
- x-audience：API 受众
- internal-component
- internal-company
- external-public
- title: API 名称
- version：API 版本
- description：API 描述
- contact/{name,url,email}：维护团队
- 使用美式英语书写
使用 JSON 作为数据交换格式
默认采用 JSON 数据类型，非 JSON 媒体类型请使用其他相应的媒体类型
JSON 应符合 RFC4627 和 RFC 7159，并满足以下的要求：
- 针对 PUT/PATCH/POST request body 以及任意响应的 response body 使用标准媒体类型
application/json - 响应和请求中优先使用以下预定义的标准字段
- createdAt
- updatedAt
- deletedAt
- 使用 UTF-8 编码
- 布尔值和数组不能使用
null - 使用UTC（世界标准时间）时间，用ISO8601进行格式化
YYYY-MM-DDTHH:MM:SSZ - API 中的 date/time 应该包含 timezone 信息 RFC3339
- 尽可能为资源提供默认的创建时间 created_at 和更新时间 updated_at
- 统一格式的国家，语言和钱币
- ISO 3166-1-alpha2 country codes
- ISO 639-1 language code 或者 BCP 47
- ISO 4217 currency codes
来自公众号 无人深空，一个专注于技术和扯淡的公众号，请不要关注
)
