[Medium翻譯]RESTful API權威設計指南－設計更好的API

對於我們開發者來說，設計與實現REST API似乎已經成為了我們的日常生活。API現在已經成為了系統間互通的預設方式。AMAZON就是一個有效的使用API進行系統間溝通的最好的例子。在這篇文章中，我將重點討論如何幫助你設計更好的API並避免一些常見的誤區。 ...

本文為授權譯文。希望查看原文的同學請戳鏈接：https://hackernoon.com/restful-api-design-step-by-step-guide-2f2c9f9fcdbf

對於我們開發者來說，設計與實現REST API似乎已經成為了我們的日常生活。API現在已經成為了系統間互通的預設方式。AMAZON就是一個有效的使用API進行系統間溝通的最好的例子。在這篇文章中，我將重點討論如何幫助你設計更好的API並避免一些常見的誤區。

傑夫貝索斯的意志－亞麻的成功之路？

可能你已經大概瞭解了傑夫貝索斯對於亞馬遜開發者的要求。如果你還沒有聽過，以下就是要點：

所有的團隊今後必須通過服務介面來開放自己的數據和服務功能。
團隊間只能通過這些介面進行通信。
其他所有的方式都不被允許：不可以直鏈，不可以直接去讀取其他隊伍的數據源，不能通過共用記憶體通信，不可以通過服務後門通信。總之，只能通過網路介面進行服務間的通信。
任何實現介面的技術都是被允許的：HTTP，Corba，Pubsub，自定義協議。貝索斯不在乎具體的實現。
所有的介面都需要被設計成可暴露型，不允許任何特例。也就是說，所有的團隊都必須計劃將自己的服務介面設計成可以被暴露給狂野的外部世界的形式。
任何人不遵守以上協議的，就滾蛋吧。

以上的要求現在看來正是亞馬遜成功的關鍵。亞馬遜在內部開發出可擴展的服務，成熟後就將這些服務暴露給外界使用。於是就有了我們所熟悉的強大的AWS。

RESTful API的設計原則

好吧，現在我們就開始瞭解一些我們設計RESTful API時需要遵守的一些原則。

能簡單就簡單 Keep It Simple

我們需要確保API的URL是簡單的。比如說，如果我們要設計一個關於產品的API，他應該是這樣的：

/products
/products/12345

第一個API用來返回所有的產品，第二個則用來返回特定的產品。

使用名詞而不是動詞

很多開發者會犯這個錯誤。他們大概忘了我們已經後HTTP的Methods來幫助我們表達動詞的部分。不如，一個用來得到所有產品的的API應該是：

/products

而不是

/getAllProducts

使用正確的HTTP方法

RESTful API有不同的方法來標示這個API操作的類型：

GET－要從服務中得到某個或者一些數據
POST－要在服務中創建某個或者一些數據
PUT/PATCH－要更新服務中的某些已有的數據
DELETE－要刪除一些服務中已有的數據

我們需要確保我們在對應的API上使用正確的HTTP方法。

使用複數

這個觀點有一些爭議。有些人喜歡在設計URL時使用複數而有些人認為保持單數更合適。比如

/products
/product

我個人喜歡使用複數。原因呢就是這樣可以避免迷惑使用者這個API到底是要返回單個數據還是一個數據的集合。同時這樣的設計也可以避免需要在Base URL疊放額外的參數，比如：/product/all

有些人可能不喜歡這個建議。那我的意見是至少你要在一個Project中保持命名的統一。

使用參數

有時候我們需要設計更複雜的API。這些API不止需要傳入id，可能還要傳入更複雜的參數。這時，我們就應該使用參數來設計API，比如：

/products?name='ABC' 就要比 /getProductsByName 要更好
/products?type='xyz' 就要比 /getProductsByType 要更好

這樣你就可以避免使用很長的URL來表達自己的意圖。設計變得更簡潔。

使用合適的HTTP狀態碼

HTTP為我們提供了豐富的狀態返回碼。然而令人遺憾的是，我們大部分人只使用了其中的兩個－200和500！這肯定不是一個很好的實踐！一下就一些你可以馬上實用的HTTP狀態碼：

200 OK－這是HTTP中最常用的狀態碼。用來標示所請求的操作成功了。
201 CREATED－這個狀態碼標示你使用POST操作所創建的資源創建成功了。
202 ACCEPTED－這個標示伺服器獲得並認可了你發送請求。
400 BAD REQUEST－這個則用來標示用戶輸入的數據有誤。
401 UNAUTHRORIZED/403 FORBINDDEN－這兩個狀態碼用來告訴用戶沒有許可權或者沒有被授權進行所請求的操作。
404 NOT FOUND－這個狀態碼用來告訴用戶你想要尋找的資源並不存在。
500 INTERNAL SERVER ERROR－你永遠不應該顯示的拋出這個異常。只有在系統異常出現時由系統自動拋出。
502 BAD GATEWAY－如果從上游的服務中收到了任何異常或者不正確的響應，這是合適的選擇。

使用版本

使用版本對於API來說是很重要的！不同的企業有不同使用版本的習慣。有些使用日期來表示版本。有些則使用查詢參數來表示版本。我個人更喜歡把版本放到URL的首碼上。比如：

/v1/products
/v2/products

而且我會儘量避免使用小版本號/v1.2/products/。因為這樣會讓人覺得你的API會頻繁的變化。同時，（.）這個點並不是能夠很快的在URL中被看到。所以，還是越簡單越好吧！

同時，保持版本的向前相容是很重要的實踐。這樣即使你改變了API版本，你的客戶也有足夠的時間來跟進你所進行的變化。

使用分頁(Pagination)

當一個API可能會返回巨量數據的時候，使用分頁成為了必須。否則用戶可能會使伺服器崩潰。

We need to always keep in mind that the API design should be full proof and fool proof.

我推薦使用limit和offset這兩個參數。比如，/products?limit=25&offset=50 同時你也要考慮設置一個預設的limit和offset。

支持的格式

選擇合適的API響應信息的格式是很重要的。大多數現代應用都會使用JSON。你也應該使用JSON，除非你有一些舊時的需求要求你使用XML響應。

回覆合適的錯誤代碼

一個很好的實踐就是保持一個服務錯誤信息的集合併加上合適的ID。比如，如果你使用過FACEBOOK的graph API，當產生錯誤時，它會給你返回：

{
  "error": {
    "message": "(#803) Some of the aliases you requested do not exist: products",
    "type": "OAuthException",
    "code": 803,
    "fbtrace_id": "FOXX2AhLh80"
  }
}

我也見過有些錯誤信息還會告訴用戶如何應對這個錯誤。這也是一個很好的實踐。