给API命名的七种优秀实践

译者 | 陈峻

审校 | 孙淑娟

如今，API已成为了现代化编程的基本组成部分。它们不但能够改善不同开发团队的协作、并鼓励创新，而且能够提高应用程序的安全性。而作为两个程序或应用之间的连接点，API端点能够起到指定资源在服务器上的确切位置的作用。

当客户端应用要向服务器端发送请求信息时，我们就需要使用API；而当服务器端接到该请求，并转呈后台数据库进行查询时，也需要调用API。因此，为了让用户能够更加容易地访问到资源，并获得良好的使用体验，我们需要通过高效的API，来保证各个端点之间的有效通信。

一、API端点是如何工作的?

如下图所示，系统的集成往往依赖于API间的通信。通常，一个系统可以使用SOAP或REST等格式,向API发送请求。服务器接收到请求后也会将响应传回给API，其中请求资源的位置就是API端点。

API的工作原理

在端点处理请求之前，客户端必须提供URL、标头、以及正文。此处的标头包含了有关请求的各种元数据，以及发送到服务器的正文详细信息。同时，服务器也可以通过连接API方法实现对数据库的访问。

API端点通常使用的是诸如：GET、DELETE、PATCH或POST等HTTP方法。这些方法决定了端点如何被使用。也就是说，当客户端发送请求时，它需要约定好用怎样的方法和URL去发起请求。

当然，这些都有固定的格式可供参考。而相对来说，命名规则比较困难，无论是API端点、网络硬件设备，还是函数与变量都会被频繁用到，而且并无固定的规则可供遵循。下面，我将和您讨论如何给API规范命名，以确保API端点能够被合理使用的7种优秀实践。

1.使用正斜杠

请始终使用正斜杠，来分隔URI资源。同时，斜杠也有助于显示资源的层次结构。

下面是一个典型的例子：

​​https://example.com/books/authors​​

2.使用动词与名词相结合的方式

通常，名词可用来描述资源是什么，而动词则被用来描述资源能做什么。因此，您应该使用动词与名词相结合的方式，来命名API资源。下面展示了一个好的API端点命名的方法和欠佳的方法：

好的命名：https://example.com/api/getBooks

欠佳的命名：http://example.com/api/books

3.使用复数名词，而不是单数

为了向用户表明服务器上有着多个资源，您应该始终以复数名词命名自己的API端点。毕竟，如果仅使用单数名词，则可能会使用户误以为该端点只提供一种资源。下面展示了一个好的API端点命名的方法和欠佳的方法：

• 好的命名：https://example.com/api/book/3
• 欠佳的命名：http://example.com/api/books/3

4.避免使用全小写字母

您不应该以全小写的形式键入API端点的URL，这会降低URL的整体可读性。下面展示了一个好的API端点命名的方法和欠佳的方法：

• 好的命名：http://example.com/api/Books/3
• 欠佳的命名：http://example.com/api/books/3

5.使用连字符分隔单词

请使用连字符（-）分隔组合的单词。毕竟，连字符比驼峰式（camel case，即每个单词的首字母大写，如：DataBaseUser）或下划线（_，有时会被遮挡住）更易读。同时，它们也更适合seo的目的。下面展示了一个好的API端点命名的方法和欠佳的方法。

• 好的命名：https://example.com/api/books/33/front-cover
• 欠佳的命名：https://example.com/api/books/33/front_cover

6.不要添加文件扩展名

尽管不会影响输出，但是扩展名会使得阅读资源变得比较困难。同时，它也会使得资源的灵活性大幅降低，不便于扩展名的更换与变化，甚至会导致中断。下面展示了一个好的API端点命名的方法和欠佳的方法。

• 好的命名https://example.com/api/books
• 欠佳的命名：https://example.com/api/books.xml

7.版本控制

如果您将来会根据业务的更新迭代，对API进行重大更改的话，应始终根据版本号来命名自己的API端点。据此，您可以轻松地区分出，来自两到多个不同API版本的资源。如下例所示，您可以在端点名称的前面，就指示好正确的版本：

​​https://example.com/api/v3/books。​​

二、小结

无论是使用新的工具，还是管理现有应用，API都能够为我们简化调用的流程。而API端点的命名和结构，直接决定了API的调用性能。因此，我们有必要通过上文提到的7种优秀实践，来创建高效的API端点，为用户提供更好的使用体验。

原文链接：https://www.makeuseof.com/api-endpoints-naming-best-practices/

译者介绍

陈峻 （Julian Chen），51CTO社区编辑，具有十多年的IT项目实施经验，善于对内外部资源与风险实施管控，专注传播网络与信息安全知识与经验。