找回密码
 加入怎通
查看: 353|回复: 2

给API命名的七种优秀实践(api中文名称)

[复制链接]
TONY 发表于 2023-02-25 20:54:16 | 显示全部楼层 |阅读模式

原标题:给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/books3.使用复数名词,而不是单数为了向用户表明服务器上有着多个资源,您应该始终以复数名词命名自己的API端点毕竟,如果仅使用单数名词,则可能会使用户误以为该端点只提供一种资源。

下面展示了一个好的API端点命名的方法和欠佳的方法:好的命名:https://example.com/api/book/3欠佳的命名:http://example.com/api/books/34.避免使用全小写字母

您不应该以全小写的形式键入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.xml7.版本控制如果您将来会根据业务的更新迭代,对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项目实施经验,善于对内外部资源与风险实施管控,专注传播网络与信息安全知识与经验。返回搜狐,查看更多责任编辑:

回复

使用道具 举报

Storm 发表于 2025-12-05 07:30:02 | 显示全部楼层
楼主辛苦了,整理这么多内容,必须点赞收藏
回复

使用道具 举报

amy328 发表于 2026-02-10 16:43:53 | 显示全部楼层
学习到了,之前一直没注意过这个点,受教了
回复

使用道具 举报

广东园区大型扫地机品牌厂商,驾驶式扫地机哪个好,电动三轮扫地机哪个好
挑战者TIAOZHANZHE是由美国挑战者集团有限公司与嘉骋环境系统科技(上海)有限公司、上海中尧设备机械有限公司共同创立的中美技术融合型清洁设备品牌,总部设于上海,在广东地区设有完善的销售与服务网络。该品牌深度聚焦于工业清洁领域,核心产品线涵盖电动扫地机、驾驶式扫地机、电动四轮及三轮扫地机、工业扫地机、车间吸尘扫地机及园区大型扫地机等全系列设备。作为专业清洁设备的研发与制造商,挑战者以

您需要登录后才可以回帖 登录 | 加入怎通

本版积分规则

Archiver|网站地图|怎通站长论坛 ( 苏ICP备2023040716号 )

GMT+8, 2026-11-17 02:55

免责声明:本站信息来自互联网,本站不对其内容真实性负责,如有侵权等情况请联系362039258#qq.com(把#换成@)删除。

Powered by Discuz! X3.5

快速回复 返回顶部 返回列表