Web API 设计指南 ​

遵循 RESTful api。考虑以下内容：

• 版本：/api/v1/
• 资源：URI表示某一资源
• 动作：HTTP方法表示对资源的操作
• 数据：JSON格式数据(请求和响应)，带校验
• 状态码：HTTP状态码表示请求结果
• 认证：OAuth 2使用了承载令牌(Bearer tokens) 并且依赖于SSL的底层传输加密。
• 缓存：ETag和Last-Modified
• 错误

1. RESTful API设计规范 ​

1.1 资源 ​

• 资源名尽可能使用名词，不使用动词
• URI中的名词表示资源的集合，使用复数形式
• URI中可以包含子资源，用/分隔，嵌套层级不要超过三层
• URI中可以包含查询参数，用?分隔
• URI中的查询参数，应该表示为资源的属性， 过滤、排序、分页等操作
• 复杂参数使用 Body（JSON 格式）

1.2 动作 ​

使用HTTP方法表示对资源的操作

• GET：查询资源
• POST：创建资源
• PUT：更新资源
• DELETE：删除资源

1.3 数据 ​

• 数据使用JSON格式
• 数据的键使用_连接单词

1.4 状态码 ​

• 200：成功（查询）
  • 201：成功，资源被创建
  • 203：成功，资源被修改
  • 204：成功，无内容（可以表示删除成功）
  • 206：部分成功（分块下载）
• 300：重定向
  • 301：永久重定向
  • 302：临时重定向
  • 304：资源未修改，使用缓存
• 400：客户端请求错误
  • 401：客户端未认证
  • 403：客户端认证通过，但是没有权限
  • 404：资源不存在
  • 405：HTTP方法不支持
  • 429：请求过多，限流
• 500：服务器内部错误
  • 501：服务器不支持当前请求所需要的某个功能(即将开业)
  • 502：网关错误
  • 503：服务器暂时不可用
  • 504：服务器处理超时

1.5 认证 ​

• OAuth 2使用了承载令牌(Bearer tokens) 并且依赖于SSL的底层传输加密。
• CORS

1.6 缓存 ​

# TODO Etag or Last-Modified

1.7 错误 ​

{
  "code": 1234,
  "message": "Something bad happened :(",
  "description": "More details about the error here"
}

PUT or POST

{
  "code": 1024,
  "message": "Validation Failed",
  "errors": [
    {
      "code": 5432,
      "field": "first_name",
      "message": "First name cannot have fancy characters"
    },
    {
      "code": 5622,
      "field": "password",
      "message": "Password cannot be blank"
    }
  ]
}

2. RESTful API设计 Checklist ​

修改自：实用 Web API 规范

3. API 文档 ​

OpenAPI API 接口规范，是一种定义 RESTful API 的标准，它是基于 Swagger 项目的开源规范，可以用 YAML 或 JSON 格式编写 API 文档。包括 API 的基本信息、整体设计、安全、请求、响应等等。

RESTful API 只是一种风格指导，没有规范（落地），OpenAPI 是一种将 RESTful API 规范化的标准，并进行扩展。

• https://openapi-map.apihandyman.io/
• https://bump.sh/blog/what-is-openapi 版本间区别

References ​

• https://www.freecodecamp.org/news/rest-api-design-best-practices-build-a-rest-api/
• https://blog.alswl.com/2023/04/web-api-guidelines/
• https://www.cnblogs.com/traditional/tag/深度解密 HTTP 协议/