给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端点命名的方法和欠佳的方法:

  • 好的命名: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项目实施经验,善于对内外部资源与风险实施管控,专注传播网络与信息安全知识与经验。

责任编辑:武晓燕 来源: 51CTO技术栈
相关推荐

2019-09-06 09:00:00

开发技能代码

2022-01-19 11:17:50

服务质量 QoS云服务网络流量

2021-07-05 10:09:52

IT领导者混合工作

2018-11-23 09:00:00

微服务微服务架构日志

2021-06-17 09:00:00

人工智能机器学习开源

2022-12-28 12:37:16

2010-12-17 11:22:11

职场

2020-01-14 08:00:00

.NET缓存编程语言

2022-05-10 08:08:01

find命令Linux

2019-10-23 09:00:00

浏览器测试工具兼容性

2022-09-24 16:44:47

数据安全数字化转型IT

2010-10-15 10:02:01

Mysql表类型

2023-01-13 16:34:08

2017-06-02 09:52:50

2017-06-14 16:44:15

JavaScript原型模式对象

2017-08-31 14:57:53

数据库MySQLJOIN

2021-07-16 09:55:46

数据工具软件

2010-08-31 10:57:36

2022-02-23 09:03:29

JavaScript开发命名约定

2020-01-14 11:09:36

CIO IT技术
点赞
收藏

51CTO技术栈公众号