Web API 设计原理和规则

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

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

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

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

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

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

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

而当今世界上最常见的 API 架构毫无疑问是 REST 。当我们使用 REST API 时，必须遵循 JSON 的规范，以有效的 JSON 格式发出测试请求。好的 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 的设计有了一定的了解了，这是无数人验证过的合理的优秀的方案，尝试一下应用到工作中吧！

如果你觉得我的分享对你有所启发或者帮助，不放点个赞，支持一下！

我叫 Eoapi，我是一款类 Postman 的开源 API 工具，我更轻量，同时可拓展！我可以简化你的 API 开发工作，让你更快更好地创建 API。

如果你对我这个开源项目感兴趣，可以来这里：
EOAPI官网或者Github

往期好文