web API设计笔记

Hello , 我是小恒。今晚就讲讲我在开发维护API后的经验分享，当然我知识有限，暂时也不会写实际操作。GitHub项目仓库有一堆还在前期开发，我的时间很多时间投在了开源上。

推荐书籍

我认为一个好的 API 设计是面向用户的，充分隐藏底层复杂原理。我们就要设计出让用户容易理解和容易使用的 API。

开发

设计 API 规范有两个方向Design-First（设计优先） 和 Code-First（代码优先）

具体不多说，参考文档https://www.codetd.com/article/11758845

资源路径设计

1）使用有意义的URL，多使用复数名词而非动词。使用小写字母，不出现下划线（比如add_books），具有唯一性的资源采用以ID作为资源标识。

2）使用层次结构以表示资源之间的关系。例如使用/users/{userId}/orders表示属于特定用户的订单。

3）使用HTTP方法表示操作,例如使用GET获取资源，使用POST创建资源，使用PUT更新资源，使用DELETE删除资源。

4）避免在路径中使用查询参数，而是将它们用于过滤、排序和分页等操作。例如，使用/users?page=1&per_page=10而不是/users/page/1/per_page/10。

数据格式

1）响应格式统一使用JSON作为数据交换格式，易于解析且跨语言兼容。

2. 响应结构应包含状态码、数据体和可选的元数据等

3. 嵌套外键关系

序列化的外键关系通常建立在一个有嵌套关系的对象之上, 例如.:

{
  "name": "service-production",
  "owner": {
    "id": "5d8201b0..."
  },
}

这种方式尽可能的把相关联的资源信息内联在一起，而不用改变响应资源的结构,或者展示更高一级的响应区域,

4）提供标准的时间戳。提供默认的资源创建时间和更新时间

异常处理

1）构建错误信息

在网络请求响应错误的时候，返回统一结构化的错误信息。要包含一个机器可读错误 code,人类可读的错误信息 message, 根据情况可以添加一个url 告诉客户端关于这个错误的更多信息以及如何去解决它

接口鉴权

这个不说了

接口维护

1）在URL中包含版本号，如/v1/users，便于管理和升级，同时保证向后兼容

2）描述API的稳定性或是它在各种各样节点环境中的完备性和稳定性

接口文档

提供详尽的API文档，说明每个端点的功能、请求参数、响应格式及示例代码

使用OpenAPI（Swagger）或Postman Collection来标准化和自动化文档生成，在springboot，django或fastapi使用Swagger可以自动生成接口文档