譯者 | 陳峻
審校 | 孫淑娟
如今，API已成為了現(xiàn)代化編程的基本組成部分。它們不但能夠改善不同開(kāi)發(fā)團(tuán)隊(duì)的協(xié)作、并鼓勵(lì)創(chuàng)新，而且能夠提高應(yīng)用程序的安全性。而作為兩個(gè)程序或應(yīng)用之間的連接點(diǎn)，API端點(diǎn)能夠起到指定資源在服務(wù)器上的確切位置的作用。
當(dāng)客戶端應(yīng)用要向服務(wù)器端發(fā)送請(qǐng)求信息時(shí)，我們就需要使用API；而當(dāng)服務(wù)器端接到該請(qǐng)求，并轉(zhuǎn)呈后臺(tái)數(shù)據(jù)庫(kù)進(jìn)行查詢時(shí)，也需要調(diào)用API。因此，為了讓用戶能夠更加容易地訪問(wèn)到資源，并獲得良好的使用體驗(yàn)，我們需要通過(guò)高效的API，來(lái)保證各個(gè)端點(diǎn)之間的有效通信。
一、API端點(diǎn)是如何工作的?
如下圖所示，系統(tǒng)的集成往往依賴于API間的通信。通常，一個(gè)系統(tǒng)可以使用SOAP或REST等格式,向API發(fā)送請(qǐng)求。服務(wù)器接收到請(qǐng)求后也會(huì)將響應(yīng)傳回給API，其中請(qǐng)求資源的位置就是API端點(diǎn)。
API的工作原理
在端點(diǎn)處理請(qǐng)求之前，客戶端必須提供URL、標(biāo)頭、以及正文。此處的標(biāo)頭包含了有關(guān)請(qǐng)求的各種元數(shù)據(jù)，以及發(fā)送到服務(wù)器的正文詳細(xì)信息。同時(shí)，服務(wù)器也可以通過(guò)連接API方法實(shí)現(xiàn)對(duì)數(shù)據(jù)庫(kù)的訪問(wèn)。
API端點(diǎn)通常使用的是諸如：GET、DELETE、PATCH或POST等HTTP方法。這些方法決定了端點(diǎn)如何被使用。也就是說(shuō)，當(dāng)客戶端發(fā)送請(qǐng)求時(shí)，它需要約定好用怎樣的方法和URL去發(fā)起請(qǐng)求。
當(dāng)然，這些都有固定的格式可供參考。而相對(duì)來(lái)說(shuō)，命名規(guī)則比較困難，無(wú)論是API端點(diǎn)、網(wǎng)絡(luò)硬件設(shè)備，還是函數(shù)與變量都會(huì)被頻繁用到，而且并無(wú)固定的規(guī)則可供遵循。下面，我將和您討論如何給API規(guī)范命名，以確保API端點(diǎn)能夠被合理使用的7種優(yōu)秀實(shí)踐。
1.使用正斜杠
請(qǐng)始終使用正斜杠，來(lái)分隔URI資源。同時(shí)，斜杠也有助于顯示資源的層次結(jié)構(gòu)。
下面是一個(gè)典型的例子：
??https://example.com/books/authors??
2.使用動(dòng)詞與名詞相結(jié)合的方式
通常，名詞可用來(lái)描述資源是什么，而動(dòng)詞則被用來(lái)描述資源能做什么。因此，您應(yīng)該使用動(dòng)詞與名詞相結(jié)合的方式，來(lái)命名API資源。下面展示了一個(gè)好的API端點(diǎn)命名的方法和欠佳的方法：
好的命名：https://example.com/api/getBooks
欠佳的命名：http://example.com/api/books
3.使用復(fù)數(shù)名詞，而不是單數(shù)
為了向用戶表明服務(wù)器上有著多個(gè)資源，您應(yīng)該始終以復(fù)數(shù)名詞命名自己的API端點(diǎn)。畢竟，如果僅使用單數(shù)名詞，則可能會(huì)使用戶誤以為該端點(diǎn)只提供一種資源。下面展示了一個(gè)好的API端點(diǎn)命名的方法和欠佳的方法：
- 好的命名：https://example.com/api/book/3
- 欠佳的命名：http://example.com/api/books/3
4.避免使用全小寫字母
您不應(yīng)該以全小寫的形式鍵入API端點(diǎn)的URL，這會(huì)降低URL的整體可讀性。下面展示了一個(gè)好的API端點(diǎn)命名的方法和欠佳的方法：
- 好的命名：http://example.com/api/Books/3
- 欠佳的命名：http://example.com/api/books/3
5.使用連字符分隔單詞
請(qǐng)使用連字符（-）分隔組合的單詞。畢竟，連字符比駝峰式（camel case，即每個(gè)單詞的首字母大寫，如：DataBaseUser）或下劃線（_，有時(shí)會(huì)被遮擋住）更易讀。同時(shí)，它們也更適合SEO的目的。下面展示了一個(gè)好的API端點(diǎn)命名的方法和欠佳的方法。
- 好的命名：https://example.com/api/books/33/front-cover
- 欠佳的命名：https://example.com/api/books/33/front_cover
6.不要添加文件擴(kuò)展名
盡管不會(huì)影響輸出，但是擴(kuò)展名會(huì)使得閱讀資源變得比較困難。同時(shí)，它也會(huì)使得資源的靈活性大幅降低，不便于擴(kuò)展名的更換與變化，甚至?xí)?dǎo)致中斷。下面展示了一個(gè)好的API端點(diǎn)命名的方法和欠佳的方法。
- 好的命名https://example.com/api/books
- 欠佳的命名：https://example.com/api/books.xml
7.版本控制
如果您將來(lái)會(huì)根據(jù)業(yè)務(wù)的更新迭代，對(duì)API進(jìn)行重大更改的話，應(yīng)始終根據(jù)版本號(hào)來(lái)命名自己的API端點(diǎn)。據(jù)此，您可以輕松地區(qū)分出，來(lái)自兩到多個(gè)不同API版本的資源。如下例所示，您可以在端點(diǎn)名稱的前面，就指示好正確的版本：
??https://example.com/api/v3/books。??
二、小結(jié)
無(wú)論是使用新的工具，還是管理現(xiàn)有應(yīng)用，API都能夠?yàn)槲覀兒?jiǎn)化調(diào)用的流程。而API端點(diǎn)的命名和結(jié)構(gòu)，直接決定了API的調(diào)用性能。因此，我們有必要通過(guò)上文提到的7種優(yōu)秀實(shí)踐，來(lái)創(chuàng)建高效的API端點(diǎn)，為用戶提供更好的使用體驗(yàn)。
原文鏈接：https://www.makeuseof.com/api-endpoints-naming-best-practices/
譯者介紹
陳峻 （Julian Chen），51CTO社區(qū)編輯，具有十多年的IT項(xiàng)目實(shí)施經(jīng)驗(yàn)，善于對(duì)內(nèi)外部資源與風(fēng)險(xiǎn)實(shí)施管控，專注傳播網(wǎng)絡(luò)與信息安全知識(shí)與經(jīng)驗(yàn)。
