您的API是什么情况?
免责声明:在纯REST中,API是不透明的,URL应该是在对先前请求的响应中作为链接发送的内容。 但是,我不是在讲纯REST,而是在讲更实用的API,其中涉及REST的一些概念以及通用的API最佳实践。
编写API时,它很简单。 您确定明显的资源并以以下端点结束:
/api.mycompany.com/tweet
最终,您的API必须捕获更复杂的概念,并为更复杂的资源建模,而这些资源无法用简短的单个名词表达。 现实世界中的一些示例包括:
- 通过请求验证器资源(AWS API Gateway API)启用请求验证
- 通过客户搜索资源执行客户搜索(Google客户搜索API)
- 通过Check Runs资源(Github API)对代码运行强大的检查
在英语语法中,实际上是两个以某种方式连接的名词的名词称为复合名词,而在英语语法中,复合名词遵循以下三种模式之一:
- 一句话:理发,牙膏
- 两个词:雨林,冰淇淋
- 连字符:自尊、,子
在API世界中,可以选择不同的选项,但是为了保持一致性,API只选择一种方法并坚持使用是更好的选择。 那么,首先,从API角度来看,复合名词有哪些选择?
骆驼香烟盒
![](/assets/blank.gif)
驼峰式大写是在短语中用大写字母写出每个单词的做法。 有两种变体:
- 首字母大写(也称为Pascal的大小写 )是首字母也是大写的地方,例如: IceCream 。 Pascal的案例在用于命名类(例如Java)的编程语言中很流行。
- 首字母小写是首字母始终小写的地方,例如: iceCream 。 这种方法在用于命名变量的编程语言( 再次是Java的一个很好的例子 )中很流行。 人们说骆驼的情况时, 通常是指最初的小写形式。
烤肉串盒
![](/assets/blank.gif)
在Kebab案例中,各个单词之间用连字符分隔。 冰淇淋表示为冰淇淋 。 Lisp编程语言在很多URL中都使用了这种方法(例如,www.blogger.com中的每个博客文章,例如http://dublintech.blogspot.com/2018/08/oauth-20-authorisation-code- grant.html)。
你们当中的观察者会注意到,有时在技术参考中使用“ 破折号”代替“ 连字符”。 那么,有什么区别呢? 在英语语法中,连字符是用来将两个单词组合成一个单词的东西,而破折号通常是用来在句子的末尾添加某种风格上的强调的东西,例如:“我在这里可能有一个有趣的观点, 您永远不会知道” 。
在编程中,我们不在乎该术语是连字符还是破折号 。 它们可互换使用,表示同一件事。
kebab案例方法在Web URI中变得很流行,因为搜索引擎知道连字符代表单独的单词,并且可以正确索引URI。 搜索引擎使用的这种约定意味着连字符已成为URI的事实上的标准。
蛇皮套
在这种方法中,下划线用于分隔单词。 冰淇淋变成冰淇淋。 除类名或静态常量外,该方法在Python和Ruby中使用。
连接词
在这种方法中,单词只是连接在一起。 没有-,没有_,也没有大写 。 这在开发人员中并不受欢迎,因为它很难阅读。
蜜蜂
我们应该在API中使用camelCase,kebab-case或snake_case吗? 不幸的是, 菲尔丁先生的论文没有这么详细。 那么人们实际上在做什么呢? 并且在API的URL和JSON主体之间使用的方法是否一致。 让我们来看看。
AWS
AWS具有用于不同服务的不同API样式。 API Gateway REST API参考显示JSON负载使用驼峰式大小写
但该网址不使用任何内容,只是:
/restapis/{id}/requestvalidators/{requestvalidatorId}
谷歌
令人惊讶,令人惊讶的是Google也有很多API 。 谷歌
![](/assets/blank.gif)
自定义搜索API与AWS API Gateway API相似。 URL中的复合名词只是一个单词,JSON主体是驼峰式大小写。
Google Gmail API在请求正文和某些URL中使用了驼峰形式,例如, 转发地址API 。
Google youtube API有时会在网址中使用kebab大小写,例如
yt-analytics,但在其他情况下将使用单个词,例如youtubepartner。 但是,JSON有效负载是驼峰式的情况。
Github
Github API是一个很好的示例,在此我们提醒您,如果可能的话,您应该尝试通过避免复合名词来避免此问题,因为它通过使用一些创造性的名称间距来避免复合名词。
![](/assets/blank.gif)
但是,还会有更多的词根出现,您会在URL中找到一个复合名词,例如使用kebab case表示的check run和使用蛇形case的JSON主体。
条纹
URL和JSON正文中的Stripe使用蛇形大小写。 例如
PaymentsIntents API 。
https://api.stripe.com/v1/payment_intents
和JSON主体...
{"id": "pi_Aabcxyz01aDfoo","object": "payment_intent","allowed_source_types": ["card"],"amount": 1099,"amount_capturable": 1000,
贝宝
贝宝(Paypal)具有比其他检查的API更多的复合名词。 用于资源(例如计费协议)的API,该API将在网址中使用kebab大小写,然后在JSON有效负载中使用蛇形大小写。
推特
Twitter在URL中使用蛇形(例如/ saved_searches /),在JSON负载中使用蛇形。
脸书
Facebook的Graph API倾向于避免URL中的资源命名,而在JSON主体中则是蛇形。
在这个阶段,您应该会有点困惑。 因此,让我们回顾一下下表。
API | 网址 | JSON正文 | |
---|---|---|---|
AWS API网关 | 没有分隔符 | 骆驼香烟盒 | |
Facebook Graph API | 不适用 | snake_case | |
Github | 蛇和烤肉串 | snake_case | |
Google自定义搜索 | 没有分隔符 | 骆驼香烟盒 | |
Google Gmail | 骆驼香烟盒 | 骆驼香烟盒 | |
领英 | 骆驼香烟盒 | 骆驼香烟盒 | |
支付宝 | 烤肉串 | snake_case | |
条纹 | snake_case | snake_case | |
推特 | snake_case | snake_case |
每个人都不一样,该怎么办?
因此,整个行业缺乏一致性。 但是,有一点值得提出:
- 通常,最好避免使用复合名词。 在所有已检查的API(贝宝除外)中,它们均出现在5%以下的API中。 这意味着当不使用他们喜欢的方法时,开发人员不会感到沮丧。
- 在上面的选择中,唯一使用复合名词的API超过5%的Web API是PayPal,它们在URI中使用kebab-case。
- kebab-case从未在任何JSON主体中使用。 允许使用语法。 那么,什么驱动了这一趋势? 这很有可能是因为JavaScript Web UI可能是受Mos流行的客户端调用API,并且类似地,为该API提供服务的最流行的后端语言是Java,而这两个家伙在它们的任何声明中都不允许使用Java。
做决定
- 如果可以,请避免使用复合名词。 这并不总是可能的。 坚持使用无处不在的语言非常重要且很有帮助。 如果您有复杂的业务应用程序,则将有很多复合名词。
- 如果您无法避免复合名词,并且超过5%的API将涉及复合名词,请使用kebab大小写作为URI。 为什么? 因为如果您拥有复杂的业务领域,则不仅需要考虑开发人员。 许多BA,产品架构师,好奇的经理也将关注您的API。 烤肉架是每个人最容易阅读的案例。
- 对于JSON主体,我认为可以使用camelCase,因为这是最容易映射回JavaScript和Java代码的方法。 Google也建议在JSON中使用camelCase 。
- 如果必须在URI中使用camelCase,请考虑对URI使用首字母大写方法,因为URI应该标记资源而不是属性。 资源更类似于Java类,Java类也使用首字母大写格式。 JSON有效负载属性类似于使用初始小写字母的Java属性。
在下一次之前,请多保重。
翻译自: https://www.javacodegeeks.com/2018/12/whats-case-api.html
您的API是什么情况?相关推荐
- api 获取网络使用情况_您的API是什么情况?
api 获取网络使用情况 免责声明:在纯REST中,API是不透明的,URL应该是对先前请求的响应中作为链接发送的内容. 但是,我不是在讲纯REST,而是在讲更实用的API,其中涉及REST的一些概念 ...
- HTML5 API 浏览器支持情况检测
HTML5发展到现在,虽说没有大规模的普及,但在我们日常生活中,也很容易见到了,HTML5的游戏.网站.应用也是层出不穷.而作为前端人员,也应该多了解这些API为以后应用打基础,下面我将给大家介绍 H ...
- 如何在YouTube Api限额的情况下获取更多视频
文章来自自己的博客 YouTube视频 谷歌限制了YouTube api v3的请求量,一天10000配额,这里不是10000次请求,每次请求根据不同参数消耗不同配额.为了摆脱这种限制而获得更多的新发 ...
- 微信小程序—调用API获取天气情况
1.在微信开发者工具中的.js文档参考wx.getLocation函数获取当前地理位置,注意在app.json文件中permission授权. "permission": {&qu ...
- 谈谈微服务设计中的API网关模式
来源:架构头条(ID: ArchFront) 原文:http://dwz.date/crrw 根据 Gartner 对微服务的定义:"微服务是范围狭窄.封装紧密.松散耦合.可独立部署且可独立 ...
- “超级”容易用错的几个Airtest和Poco的API,看看你有没有遇到过
前言 最近在我们的答疑群里面,经常遇到这样一类情况: 错把Airtest的API强行用在Poco控件上面 错把Poco的API强加在Airtest的截图脚本上面 不管API的实际用法如何,只按自己的臆 ...
- Asp.Net Web API 2第一课——入门
前言 Http不仅仅服务于Web Pages.它也是一个创建展示服务和数据的API的强大平台.Http是简单的.灵活的.无处不在的.你能想象到几乎任何的平台都会有HTTP服务库.HTTP服务可以涉及到 ...
- 1.1ASP.NET Web API 2入门
HTTP 不只是为了生成 web 页面.它也是建立公开服务和数据的 Api 的强大平台.HTTP 是简单的. 灵活的和无处不在.你能想到的几乎任何平台有 HTTP 库,因此,HTTP 服务可以达到范围 ...
- 猫头鹰的深夜翻译:API网关的重要性
前言 在非技术术语中,"网关或门是进入一个由墙围住的封闭空间的入口点."同理,API网关是指位于防火墙或互联网后面 的服务的入口点.在微服务的世界中,网关坐镇于API前面,直接面向 ...
最新文章
- 2021年大数据Flink(三十四):​​​​​​​Table与SQL ​​​​​​案例一
- java面向对象(包package)
- sftp进入指定目录_CentOS7服务搭建----搭建SFTP(安全文件传送协议)服务器
- uniapp中动态修改导航栏标题
- linux shell which 和 whereis 区别
- 玩玩自动化测试之selenium篇
- 蓝牙连接不上车要hfp_科普|蓝牙耳机小知识,这些都不知道难怪你选不到好的蓝牙耳机...
- 采访问题 What is your role at XX and what are your responsibilities
- python实际应用方面的材料_python应用于哪些方面
- form表单ajax提交 ac,請求Ajax 帶返回值的通用方法, 自動獲取頁面控件值(form表單post方法提交 ),自動給控件賦值...
- Python poetry的使用
- 启动时间知多少?8款音视频类应用测评报告分析
- CAS 配置NLB 负载均衡网络无法连接
- python按字节读文件-使用Python进行二进制文件读写(转)
- 华为手机楷体字体下载_正楷字体下载正楷字体官方下载[字体下载]-华军软件园...
- 英语动词过去式和过去分词
- android 高德地图 定位蓝点消失,高德地图蓝点定位不显示蓝点
- i3 10100F和R3 3200G哪个好
- python+adb游戏辅助脚本
- Varian OBI几个奇葩之处