免责声明：在纯REST中，API是不透明的，URL应该是在对先前请求的响应中作为链接发送的内容。 但是，我不是在讲纯REST，而是在讲更实用的API，其中涉及REST的一些概念以及通用的API最佳实践。
编写API时，它很简单。 您确定明显的资源并以以下端点结束：

/api.mycompany.com/tweet

最终，您的API必须捕获更复杂的概念，并为更复杂的资源建模，而这些资源无法用简短的单个名词表达。 现实世界中的一些示例包括：

• 通过请求验证器资源（AWS API Gateway API）启用请求验证
• 通过客户搜索资源执行客户搜索（Google客户搜索API）
• 通过Check Runs资源（Github API）对代码运行强大的检查

在英语语法中，实际上是两个以某种方式连接的名词的名词称为复合名词，而在英语语法中，复合名词遵循以下三种模式之一：

1. 一句话：理发，牙膏
2. 两个词：雨林，冰淇淋
3. 连字符：自尊、,子

在API世界中，可以选择不同的选项，但是为了保持一致性，API只选择一种方法并坚持使用是更好的选择。 那么，首先，从API角度来看，复合名词有哪些选择？

骆驼香烟盒

驼峰式大写是在短语中用大写字母写出每个单词的做法。 有两种变体：

1. 首字母大写（也称为Pascal的大小写 ）是首字母也是大写的地方，例如： IceCream 。 Pascal的案例在用于命名类（例如Java）的编程语言中很流行。
2. 首字母小写是首字母始终小写的地方，例如： iceCream 。 这种方法在用于命名变量的编程语言（ 再次是Java的一个很好的例子 ）中很流行。 人们说骆驼的情况时， 通常是指最初的小写形式。

烤肉串盒

在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 。 谷歌

自定义搜索API与AWS API Gateway API相似。 URL中的复合名词只是一个单词，JSON主体是驼峰式大小写。

Google Gmail API在请求正文和某些URL中使用了驼峰形式，例如， 转发地址API 。

Google youtube API有时会在网址中使用kebab大小写，例如
yt-analytics，但在其他情况下将使用单个词，例如youtubepartner。 但是，JSON有效负载是驼峰式的情况。

Github

Github API是一个很好的示例，在此我们提醒您，如果可能的话，您应该尝试通过避免复合名词来避免此问题，因为它通过使用一些创造性的名称间距来避免复合名词。

但是，还会有更多的词根出现，您会在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

每个人都不一样，该怎么办？

因此，整个行业缺乏一致性。 但是，有一点值得提出：

1. 通常，最好避免使用复合名词。 在所有已检查的API（贝宝除外）中，它们均出现在5％以下的API中。 这意味着当不使用他们喜欢的方法时，开发人员不会感到沮丧。
2. 在上面的选择中，唯一使用复合名词的API超过5％的Web API是PayPal，它们在URI中使用kebab-case。
3. kebab-case从未在任何JSON主体中使用。 允许使用语法。 那么，什么驱动了这一趋势？ 这很有可能是因为JavaScript Web UI可能是受Mos流行的客户端调用API，并且类似地，为该API提供服务的最流行的后端语言是Java，而这两个家伙在它们的任何声明中都不允许使用Java。

做决定

1. 如果可以，请避免使用复合名词。 这并不总是可能的。 坚持使用无处不在的语言非常重要且很有帮助。 如果您有复杂的业务应用程序，则将有很多复合名词。
2. 如果您无法避免复合名词，并且超过5％的API将涉及复合名词，请使用kebab大小写作为URI。 为什么？ 因为如果您拥有复杂的业务领域，则不仅需要考虑开发人员。 许多BA，产品架构师，好奇的经理也将关注您的API。 烤肉架是每个人最容易阅读的案例。
3. 对于JSON主体，我认为可以使用camelCase，因为这是最容易映射回JavaScript和Java代码的方法。 Google也建议在JSON中使用camelCase 。
4. 如果必须在URI中使用camelCase，请考虑对URI使用首字母大写方法，因为URI应该标记资源而不是属性。 资源更类似于Java类，Java类也使用首字母大写格式。 JSON有效负载属性类似于使用初始小写字母的Java属性。

在下一次之前，请多保重。

翻译自: https://www.javacodegeeks.com/2018/12/whats-case-api.html