免責(zé)聲明：在純REST中，API是不透明的，URL應(yīng)該是在對先前請求的響應(yīng)中作為鏈接發(fā)送的內(nèi)容。 但是，我不是在講純REST，而是在講更實(shí)用的API，其中涉及REST的一些概念以及通用的API最佳實(shí)踐。
編寫API時(shí)，它很簡單。 您確定明顯的資源并以以下端點(diǎn)結(jié)束：

/api.mycompany.com/tweet

最終，您的API必須捕獲更復(fù)雜的概念，并為更復(fù)雜的資源建模，而這些資源無法用簡短的單個(gè)名詞表達(dá)。 現(xiàn)實(shí)世界中的一些示例包括：

• 通過請求驗(yàn)證器資源（AWS API Gateway API）啟用請求驗(yàn)證
• 通過客戶搜索資源執(zhí)行客戶搜索（Google客戶搜索API）
• 通過Check Runs資源（Github API）對代碼運(yùn)行強(qiáng)大的檢查

在英語語法中，實(shí)際上是兩個(gè)以某種方式連接的名詞的名詞稱為復(fù)合名詞，而在英語語法中，復(fù)合名詞遵循以下三種模式之一：

一句話：理發(fā)，牙膏

兩個(gè)詞：雨林，冰淇淋

連字符：自尊、,子

在API世界中，可以選擇不同的選項(xiàng)，但是為了保持一致性，API只選擇一種方法并堅(jiān)持使用是更好的選擇。 那么，首先，從API角度來看，復(fù)合名詞有哪些選擇？

駱駝香煙盒

駝峰式大寫是在短語中用大寫字母寫出每個(gè)單詞的做法。 有兩種變體：

首字母大寫（也稱為Pascal的大小寫 ）是首字母也是大寫的地方，例如： IceCream 。 Pascal的案例在用于命名類（例如Java）的編程語言中很流行。

首字母小寫是首字母始終小寫的地方，例如： iceCream 。 這種方法在用于命名變量的編程語言（ 再次是Java的一個(gè)很好的例子 ）中很流行。 人們說駱駝的情況時(shí)， 通常是指最初的小寫形式。

烤肉串盒

在Kebab案例中，各個(gè)單詞之間用連字符分隔。 冰淇淋表示為冰淇淋 。 Lisp編程語言在很多URL中都使用了這種方法（例如，www.blogger.com中的每個(gè)博客文章，例如http://dublintech.blogspot.com/2018/08/oauth-20-authorisation-code- grant.html）。

你們當(dāng)中的觀察者會(huì)注意到，有時(shí)在技術(shù)參考中使用“ 破折號(hào)”代替“ 連字符”。 那么，有什么區(qū)別呢？ 在英語語法中，連字符是用來將兩個(gè)單詞組合成一個(gè)單詞的東西，而破折號(hào)通常是用來在句子的末尾添加某種風(fēng)格上的強(qiáng)調(diào)的東西，例如：“我在這里可能有一個(gè)有趣的觀點(diǎn)， 您永遠(yuǎn)不會(huì)知道” 。

在編程中，我們不在乎該術(shù)語是連字符還是破折號(hào) 。 它們可互換使用，表示同一件事。

kebab案例方法在Web URI中變得很流行，因?yàn)樗阉饕嬷肋B字符代表單獨(dú)的單詞，并且可以正確索引URI。 搜索引擎使用的這種約定意味著連字符已成為URI的事實(shí)上的標(biāo)準(zhǔn)。

蛇皮套

在這種方法中，下劃線用于分隔單詞。 冰淇淋變成冰淇淋。 除類名或靜態(tài)常量外，該方法在Python和Ruby中使用。

連接詞

在這種方法中，單詞只是連接在一起。 沒有-，沒有_，也沒有大寫 。 這在開發(fā)人員中并不受歡迎，因?yàn)樗茈y閱讀。

蜜蜂

我們應(yīng)該在API中使用camelCase，kebab-case或snake_case嗎？ 不幸的是， 菲爾丁先生的論文沒有這么詳細(xì)。 那么人們實(shí)際上在做什么呢？ 并且在API的URL和JSON主體之間使用的方法是否一致。 讓我們來看看。

AWS

AWS具有用于不同服務(wù)的不同API樣式。 API Gateway REST API參考顯示JSON負(fù)載使用駝峰式大小寫
但該網(wǎng)址不使用任何內(nèi)容，只是：

/restapis/{id}/requestvalidators/{requestvalidatorId}

谷歌

令人驚訝，令人驚訝的是Google也有很多API 。 谷歌

自定義搜索API與AWS API Gateway API相似。 URL中的復(fù)合名詞只是一個(gè)單詞，JSON主體是駝峰式大小寫。

Google Gmail API在請求正文和某些URL中使用了駝峰形式，例如， 轉(zhuǎn)發(fā)地址API 。

Google youtube API有時(shí)會(huì)在網(wǎng)址中使用kebab大小寫，例如
yt-analytics，但在其他情況下將使用單個(gè)詞，例如youtubepartner。 但是，JSON有效負(fù)載是駝峰式的情況。

Github

Github API是一個(gè)很好的示例，在此我們提醒您，如果可能的話，您應(yīng)該嘗試通過避免復(fù)合名詞來避免此問題，因?yàn)樗ㄟ^使用一些創(chuàng)造性的名稱間距來避免復(fù)合名詞。

但是，還會(huì)有更多的詞根出現(xiàn)，您會(huì)在URL中找到一個(gè)復(fù)合名詞，例如使用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更多的復(fù)合名詞。 用于資源（例如計(jì)費(fèi)協(xié)議）的API，該API將在網(wǎng)址中使用kebab大小寫，然后在JSON有效負(fù)載中使用蛇形大小寫。

推特

Twitter在URL中使用蛇形（例如/ saved_searches /），在JSON負(fù)載中使用蛇形。

臉書

Facebook的Graph API傾向于避免URL中的資源命名，而在JSON主體中則是蛇形。

在這個(gè)階段，您應(yīng)該會(huì)有點(diǎn)困惑。 因此，讓我們回顧一下下表。

API 網(wǎng)址 JSON正文

AWS API網(wǎng)關(guān)	沒有分隔符	駱駝香煙盒
Facebook Graph API	不適用	snake_case
Github	蛇和烤肉串	snake_case
Google自定義搜索	沒有分隔符	駱駝香煙盒
Google Gmail	駱駝香煙盒	駱駝香煙盒
領(lǐng)英	駱駝香煙盒	駱駝香煙盒
支付寶	烤肉串	snake_case
條紋	snake_case	snake_case
推特	snake_case	snake_case

每個(gè)人都不一樣，該怎么辦？

因此，整個(gè)行業(yè)缺乏一致性。 但是，有一點(diǎn)值得提出：

通常，最好避免使用復(fù)合名詞。 在所有已檢查的API（貝寶除外）中，它們均出現(xiàn)在5％以下的API中。 這意味著當(dāng)不使用他們喜歡的方法時(shí)，開發(fā)人員不會(huì)感到沮喪。

在上面的選擇中，唯一使用復(fù)合名詞的API超過5％的Web API是PayPal，它們在URI中使用kebab-case。

kebab-case從未在任何JSON主體中使用。 允許使用語法。 那么，什么驅(qū)動(dòng)了這一趨勢？ 這很有可能是因?yàn)镴avaScript Web UI可能是受Mos流行的客戶端調(diào)用API，并且類似地，為該API提供服務(wù)的最流行的后端語言是Java，而這兩個(gè)家伙在它們的任何聲明中都不允許使用Java。

做決定

如果可以，請避免使用復(fù)合名詞。 這并不總是可能的。 堅(jiān)持使用無處不在的語言非常重要且很有幫助。 如果您有復(fù)雜的業(yè)務(wù)應(yīng)用程序，則將有很多復(fù)合名詞。

如果您無法避免復(fù)合名詞，并且超過5％的API將涉及復(fù)合名詞，請使用kebab大小寫作為URI。 為什么？ 因?yàn)槿绻鷵碛袕?fù)雜的業(yè)務(wù)領(lǐng)域，則不僅需要考慮開發(fā)人員。 許多BA，產(chǎn)品架構(gòu)師，好奇的經(jīng)理也將關(guān)注您的API。 烤肉架是每個(gè)人最容易閱讀的案例。

對于JSON主體，我認(rèn)為可以使用camelCase，因?yàn)檫@是最容易映射回JavaScript和Java代碼的方法。 Google也建議在JSON中使用camelCase 。

如果必須在URI中使用camelCase，請考慮對URI使用首字母大寫方法，因?yàn)閁RI應(yīng)該標(biāo)記資源而不是屬性。 資源更類似于Java類，Java類也使用首字母大寫格式。 JSON有效負(fù)載屬性類似于使用初始小寫字母的Java屬性。

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

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

創(chuàng)作挑戰(zhàn)賽新人創(chuàng)作獎(jiǎng)勵(lì)來咯，堅(jiān)持創(chuàng)作打卡瓜分現(xiàn)金大獎(jiǎng)

總結(jié)

以上是生活随笔為你收集整理的您的API是什么情况？的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。