REST API设计的最佳实践

前言¶

注：这是一篇英文翻译，原文标题 REST API Design Best Practices, 作者是Dr Milan Milanović

原文: https://newsletter.techworld-with-milan.com/p/rest-api-design-best-practices

术语 API(Application Programming Interface)，指定是在多个程序服务之间的一种通信方式，一般是在叫做客户端(client)和服务器(server)之间传递请求(request)和响应(response)。

有多种类型的API协议：

• REST：基于客户端和服务器端角色的划分，拆分成前端(frontend)和和后端(backend)API，已在开发实现阶段更加灵活的推进
• RPC：通过 RPC(remote procedural call) 协议，传递多个参数和接收处理结果
• SOAP：在互联网上支持广泛的通信协议，比如HTTP、SMTP和TCP
• WebSocket：提供一种稳定连续的连接方式，供浏览器和服务器之间交换数据

REST API的设计¶

作为软件工程师，在日常工作中，大部分人都在使用或创建REST API。

在系统之间通信的标准做法是通过API，正确的建立REST API可以避免在将来产生问题，一个定义良好的API应该易于使用、简洁并且不易滥用。

这有一些建议：

• 1、用名词代替动词:

动词不应出现在最终路径中，相反，路径名应该包含名词来表明当前访问或改变的对象是什么，比如，不要使用 /getAllClients 来获取所有客户信息，而是使用 /clients

• 2、使用名词的复数形式:

尝试使用名词的复数形式表示资源，这个适用于所有类型，比如，不要使用 /employee/:id/，而是使用 /employees/:id/

• 3、保持一致性:

当提到一致性时，常意味着更好的关联性。当已经有一个路径定义时，那么相同的类似操作应该都使用统一的做法，比如相同的授权方式、头部、状态码等。

• 4、保持简单:

定义路径时应该面向资源，尽量保持原有的样子，比如定义一个用户资源API，可以这样定义:

/users

/users/124

这里第1个API是获取所有用户资源，而第2个事获取特定的用户资源

• 5、使用合适的状态码:

这个非常重要，有很多种状态码，但我们平时只使用一小部分，比如:

- 200：常规的成功响应
- 201：创建成功
- 202：请求成功
- 204：无内容
- 307：跳转内容
- 400：错误请求
- 401：未通过登录授权的请求
- 403：缺少权限
- 404：找不到资源
- 5xx：内部错误

• 6、不要返回纯文本信息:

REST API应该接收JSON作为请求数据，同时也响应JSON数据，因为这是数据传输的一个标准。但是，响应的时候不仅仅是返回一个JSON格式的字符串，还需要指定header中的 Content-Type 属性值为 application/json。唯一的例外是当我们传输或接收文件时。

• 7、使用合适的错误处理:

当有错误产生的时候，我们想要避免产生歧义，因此要合适的处理错误并根据错误类型返回对应的响应码，比如400到5xx错误。在返回状态码的同时，应该也响应中包含一些关于错误的细节信息。

• 8、有好的安全措施:

我们希望客户端和服务器之间的通信都是受到保护的，那就意味着我们整个过程都一直需要SSL/TLS，没有例外。当前，也可以通过API key进行授权，那就需要使用一个定制的特殊HTTP Header，并且指定过期时间。

• 9、使用分页器:

如果我们的API需要返回很多数据，那么就是要分页器，这会让我们的API更有前瞻性，便于将来扩展。这有一个使用page和page_size的例子： /products?page=10&page_size=20

• 10、区分版本:

从API的第1个版本开始就记录版本号，这个很重要，因为总是会有不同的人使用我们不同版本的API；通过版本号的区分，就可以不让用户受到后续版本改变的影响。API的版本号可以通过HTTP Header或者路由路径参数方式提供。

比如: /products/v1/4

同样，不要忘记为API撰写文档，因为API好不好用全依赖于文档写的好不好。文档中应该包含请求和响应的完整例子，这里我们可以直接使用OpenAPI生成的文档。

工具¶

如果你想要开始开发API，可以了解一下Swagger或OpenAPI的使用方法，也可以借助Postman和Stoplight工具，这里有一个由G2产生的完整清单:

词汇¶