给API命名的七种优秀实践 _API

本文通过展示7种优秀API命名实践，来协助您创建高效的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端点命名的方法和欠佳的方法：