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