api数据加密的定义_API 设计基础规范

首先，请务必记住 API 设计和使用的一个重要法则 Postel's Law(又称作稳健性原则):

• Be liberal in what you accept, be conservative in what you send

下面是关于 API 设计的一些基本问题

API First

将 API 视作产品，并向产品开发一样设计和维护 API

1. 在代码实现前的 Design 阶段，就优先定义符合标准规范的 API
2. 与客户(API 的使用者)一起设计和审查 API
3. 设计可用性、可读性和可维护性的 API
4. 长期积极维护 API 并保持 API 的一致性

代码结构

项目(Git Repo) 中应包含以下目录用于描述 API

• README.MD
  • 可以包含服务 API Spec 的 Jira Link
• 文档
  • 在 doc/* 目录下的 markdown 文件或链接到 git
• 接口定义
  • 按 API 版本分目录 v[0-9]*/*
  • 每个版本中需包含 swagger yaml 文件

安全

无论是 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 可以使用协商的加密认证算法

命名规范

1. 总是使用小驼峰
2. 使用美式英语
3. 允许使用缩写
   1. 产品名
   2. API
   3. config (configuration)
   4. id (identifier)
   5. spec (specification)
   6. stats (statistics)
4. 使用准确描述 API 的命名，而非笼统模糊的命名(如 items)
5. 尽量避免使用编程语言中的保留字

文档

遵循 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，并满足以下的要求：

1. 针对 PUT/PATCH/POST request body 以及任意响应的 response body 使用标准媒体类型 application/json
2. 响应和请求中优先使用以下预定义的标准字段
   1. createdAt
   2. updatedAt
   3. deletedAt
3. 使用 UTF-8 编码
4. 布尔值和数组不能使用 null
5. 使用UTC（世界标准时间）时间，用ISO8601进行格式化YYYY-MM-DDTHH:MM:SSZ
6. API 中的 date/time 应该包含 timezone 信息 RFC3339
7. 尽可能为资源提供默认的创建时间 created_at 和更新时间 updated_at
8. 统一格式的国家，语言和钱币
   1. ISO 3166-1-alpha2 country codes
   2. ISO 639-1 language code 或者 BCP 47
   3. ISO 4217 currency codes

来自公众号 无人深空，一个专注于技术和扯淡的公众号，请不要关注