审校 | 孙淑娟
如今,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项目实施经验,善于对内外部资源与风险实施管控,专注传播网络与信息安全知识与经验。