REST API 設計與開發最佳實踐

并非标準，用它來提供各種服務，可以用各種程式設計語言來實作。

在本篇文章中，我們的目标是一起清晰的了解 REST，知道何時用以及如何使用它，以及REST的本質。

我們将通過一些基礎知識和定義，包括REST API的最佳實踐，可以讓各位能夠用任何開發語言來實作REST API。

建議您有HTTP協定基礎，或者了解一部分，可以充分消化這部分内容。

REST的本質

REST - Representational State Transfer是Roy Field博士創立的一種架構風格，他在UC Irvine的論文中描述了架構風格與基于Web的軟體架構設計，并使用HTTP 1.1開發。

我們使用REST做為網際網路上不同計算機系統間通信的一種方式。

REST綁定HTTP

根據REST定義，并非如此。盡管人們可以使用其它一些REST應用程式協定，但在涉及REST實作時，HTTP仍然是應用程式協定中無可争辯的主流。

RESTful API的含義

RESTful有下列一些特點：

1、用戶端/伺服器架構：完整的服務由前端“用戶端”和整個系統的後端“伺服器”組成。

2、無狀态：伺服器在不同請求中間不儲存任何狀态。會話的狀态完全由用戶端負責。根據REST的定義：所有REST互動都是無狀态的，也就是說，每個請求都包含連接配接器了解請求所需的全部資訊，而不受任何先前可能發生的請求影響。

3、可緩存：用戶端應該能夠将響應存儲在緩存中，以便獲得更好的性能。

RESTful API遵循以上這些規則，并使用HTTP方法來操作資源集的服務。

為什麼需要用 Restful API

因為它們提供了一種簡單、靈活和可擴充的方式來開發Web通信的分布式應用程式。

我們可能有很多REST API。如果業務足夠廣，需要開放的服務也會變得複雜。

開發者需要一些實用主義才能做出好的應用和服務。

理論對于認知了解很重要，但理論的實施才是區分優劣應用差異的檢驗标準。為此，我們要聰明的工作，但一定要記得，最終使用者才是第一優先級，是最高價值。

我們知道了重點，讓API做得強大易，讓使用者的工作也變得更容易 。

抽象與具體業務 API

在開發軟體時，我們會經常使用面向對象的抽象和多态來開發應用程式。這樣可以最大化重用代碼。

那麼，我們是不是也應該這樣開發REST API？

到開發API的情況就不同了，對于REST API，具體比抽象更好。也就是完成實際的功能更好。我們來看一些執行個體：

有兩個api版本：

/entities

/entitie

/owners

/blogs

/blogposts

您做為開發者，哪個描述會更清楚，您願意用哪個API？我選擇第二個。

URI格式，使用名詞而非動詞

下面是API開發的另一個最佳實踐。我們如何格式化你的結點？如果你使用編碼的方法來命名URI結點，會是以下的結果：

/getAllBlogPosts

/updateBlogPost/12

/deleteBlogPost/12

/updateAuthor/3

/deleteAuthor/3

我想您已經明白，這會有很多個URL結點，每個結點隻做一件事情。

我們要有一個更系統的命名來精簡梳理上面這個攤子。先把資源用名詞來描述，把HTTP方法換成動詞。于是我們會得到下面這樣的結果：

GET /blogpsots - 取得所有的部落格

GET /blogposts/12 - 取得ID為12的部落格

POST /blogposts - 添加一個新的部落格，傳回錯誤資訊

DELETE /blogposts/12 - 删除ID為12的部落格

GET /author/3/blogposts - 擷取ID為3的作者全部部落格

這樣，一個更簡潔，精确的API 就出現了。對于使用的使用者來講，他會馬上清楚。當然，你可以使用單數形式而不是複數形式，這樣顯得資源名稱更為整潔，您根據自己的喜好，這點取決于自己。

錯誤處理

本階段是API開發的另一個重要方面。有好幾個很好的方法來處理錯誤。

我們來看一些進階的開發狗是咋幹的：

Twitter:

請求：GET https://api.twitter.com/1.1/account/settings.json 響應：狀态碼 400 {"errors":[{"code":215,"message":"Bad Authentication data."}]}

Twitter給我們的狀态碼和錯誤碼，以及一個簡短說明。

Facebook：

請求：GET https://graph.facebook.com/me/photos {    "error": {       "message": "An active access token must be used to query information about the current user.",       "type": "OAuthException",       "code": 2500,       "fbtrace_id": "DzkTMkgIA7V"    } }

Facebook給夠給你一個更具體的錯誤資訊。

Twilio：

請求：GET https://api.twilio.com/2010-04-01/Accounts/1234/IncomingPhoneNumbers/1234 響應：狀态碼 404 <?xml version='1.0' encoding='UTF-8'?> <TwilioResponse>     <RestException>         <Code>20404</Code>         <Message>The requested resource /2010-04-01/Accounts/1234/IncomingPhoneNumbers/1234 was not found</Message>         <MoreInfo>https://www.twilio.com/docs/errors/20404</MoreInfo>         <Status>404</Status>     </RestException> </TwilioResponse>

Twilio給我們一個XML響就格式，并且能夠鍊到你能找到錯誤細節的文檔。

我們看到，不同的開發者提供方法存在一些差別。但是這些開放平台都提供了具體的錯誤資訊，不會隻簡單告訴使用者不可用，讓使用者不知道發生了什麼，讓他們在搜尋引擎無目的的搜尋隻會浪費時間。

傳回狀态碼

在設計REST API時，需要使用HTTP狀态代碼與API進行通信。 

如你所想，HTTP有很多現成狀态碼，可以描述一些可能的響應。

但是，我們應該用多少？我們應該對每一種情況都有嚴格的狀态編碼麼？

HTTP狀态碼超過70個狀态，你知道他們的核心嗎？ API使用者是否會用到它們，避免讓大家再去查。我們大多數都熟悉以下的狀态碼：

200 OK  

400 Bad Request  

500 Internal Server Error  

我們先從這三點開始，來逐漸覆寫REST API的大部分功能。

其它常見的狀态碼：

201 Created  

204 No Content  

401 Unauthorized  

403 Forbidden  

404 Not Found  

可以通過功能幫助使用者快速找出結果。 如果覺得狀态代碼不夠在錯誤處理顯示描述性内容，那麼應該包含某類型的消息。 再通過代碼和描述性資訊來幫助API使用者。

安全

REST API安全性依賴于标準的HTTP機制，如基本認證或摘要認證 。

每個請求都應該通過HTTPS進行 。

提高REST API的安全性有很多技巧，但是由于REST的無狀态特性，在實作它們時請務必小心謹慎。 比如最後一個請求的狀态未傳回， 用戶端應該存儲和驗證狀态。

另外，使用時間戳和記錄請求對我們也有很大幫助。

關于此話題還有很多要說的，但不在本文的讨論範圍内。 如果您想了解更多關于HTTP安全的資訊，請查閱21CTO公衆号或社群網站。

REST API版本控制

我們已經編寫了REST API，許多使用者已經用上了它，我們對此感到滿意。 

但是出現了新功能，需要增加或修改原有功能和方法，有可能還是很大的變化。

不必擔心，我們有解決方案。

在開始開發API之前，我們可以通過将API版本前添加到URI端點，以此達到API版本化。如下：

https://api.21cto.com/v1/authors/2/blogposts/13

這樣，隻要API發生重大變更，就可以随時增加API版本号（比如，v2，v3 ...）。 這也向使用者發出信号，說明一些重要的變化，使用新版本時應該小心。

文檔的重要性

這是一個簡而易見的方法。您可能是世界上最好的API開發者，但如若沒有文檔，API就失去一半的生命力。

正确完整的文檔對于每個軟體産品和Web服務都至關重要。

當然，您當然可以通過保持一緻并使用清晰的描述性文法來讓使用者很容易的學習。 但是，好的文檔仍然不可或缺。

以下是一些開放平台API的文檔例子：

https://www.twilio.com/docs/api/rest/

https://developers.facebook.com/docs/

https://developers.google.com/maps/documentation/

有很多工具可以我們開發和調試API，但是不要忘了添加人的測試和了解，讓一個人可以正确了解您的思維。

結論

我們在本文了解了建構REST API的概念，并介紹了一些REST API的最佳開發實踐。 如果您第一次嘗試開發自己的REST API。 可以嘗試在本文中的REST API最佳實踐。

先從最小的API開始，遵循這幾個實踐，相信您會成就感滿滿。

後面我們有一個持續的系列文章，展示相關語言開發實踐。 比如您是C#或者Java專家，了解如何以幾種不同的方式使用RESTful API 。

我還錯過了什麼内容嗎？如果您知道還有更重要的，歡迎在本文底部發表評論~