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