关于API：好的设计和坏的设计【eolink翻译】

以前开发或更新 API 时，我们经常需要深入讨论对 API 的结构、命名和功能等，这个花费了大量的时间。

随着 API 行业的蓬勃发展，API 设计也越来越重要。这么多年发展下来，一些如REST API之类的规则也受到大多数人认可，这些规则可以应用于开发流程中，帮助团队快速达成共识，达到提效的目的。

接下来会介绍 API 设计的原理和规则。而在本文中，我们将专注于 Web API。

先用一句话来解释一下，API 是 Application（应用程序）、Programming（编程）和 Interface（接口）的缩写组合，顾名思义，通过一个编写好的接口，连接两个应用程序，可以内部使用，也可以对外开放。

基本上，每次我们使用 Web 应用程序、发送消息或访问某个 URL 时，都在使用对应的 API ，无论它是客户端应用程序还是服务器应用程序，都是通过 API 来传递数据。

由于 API 和其他一切之间的所有通信都是通过 HTTP 完成的，因此 HTTP 非常重要，需要根据不同的目的和需求，采用不同的请求方法：

• GET — 请求指定资源的表示。使用 GET 的请求应该只检索数据。

• POST — 向指定资源提交数据。

• PUT — 用请求数据替换目标资源的所有当前表示。

• DELETE — 删除指定的资源。

• PATCH — 对资源应用部分修改。

具体的用法可以在公众号其他文章中了解，网上也有很多相关的内容，就不过多展开。

开发技术在不断发展，API 架构和协议也越来越多。不同的架构和协议，在制定数据类型、命令方式、功能上都有所不同。以前最流行的是基于 XML 的协议，现在也逐渐被 JSON 取代。

而当今世界上最常见的 API 架构毫无疑问是 REST 。当我们使用 REST API 时，必须遵循 JSON 的规范，以有效的 JSON 格式发出测试请求。好的 API 通常会遵循这些规则：

• API 必须与后端、数据存储、客户端等分开。考虑到安全性和灵活性，API 必须是单独的层级；

• 不同的请求应该互不干扰，独立处理。这也意味着每个请求都需要包含处理它所需的所有信息；

• API 应该独立于客户端外发送请求，以相同的方式工作。例如在 Web 服务器、负载平衡器还是任何其他客户端；

• 资源应该在客户端或服务器端应该是可缓存的。这可以提高客户端的性能，同时提高服务器端的可拓展性；

• 处理错误并返回相应的错误代码。帮助用户了解是404还是其他问题；

• API 必须是有容错的。用户有时因为物理原因如网络超时等，发出了重复的请求，这样的请求应该返回相同的结果；

• 使用 Eolink 或其他工具生成规范的 API 文档。不管是使用还是工作交接，都需要用到 API 文档。

命名端点也有一些很好的方式：

• 只使用名词：端点应该用指定资源内容的名词命名，而不是为正在执行的功能添加动词。例如命名端点 /users 并使用不同的 HTTP 方法来处理用户实体，而不是创建多个 /get-user 、/add-user 等端点；

• 使用清晰的名称：端点的名称应该清晰直观。不要使用任何快捷方式或缩写，除非很明显 - /ids 是可以理解的并且比 /identification-numbers 更可取；

• 通过正斜杠构建层次结构：将端点分组为逻辑组。如 /departments/ids 和 /departments/managers ，比 /departments-ids 和 /departments-managers 更好；

• 仅使用小写：URL 是区分大小写的，因此最好尽量避免使用大写；

• 使用“-”分隔单词：端点名称中的不同单词通常用“-”分隔，而不是下划线或骆驼拼写法；

• 避免使用特殊字符：URL 只能使用 ASCII 字符集发送和接收，因此可以只使用该字符集中的字符。同时其他如“%”，“[]”，“{} ”,“|”,“,”“<>” 最好也尽量避免使用。

大多数 REST API 是与微服务架构一起制作的。

在这种情况下，这种 API 结构将提供更改底层逻辑、添加或删除组件等的灵活性，而无需更改与其他服务的其他通信协议。

相信你也对 Web API 的设计有了一定的了解了，这是无数人验证过的合理的优秀的方案，尝试一下应用到工作中吧！

图中所使用的的接口管理工具是eolink，感兴趣可以自行使用：www.eolink.com