淺談RESTful

淺談RESTful

什麼是RESTful?

　　REST全稱是Representational State Transfer，中文意思是表述（編者注：一般譯爲表徵）性狀態轉移。 它首次出如今2000年Roy Fielding的博士論文中，Roy Fielding是HTTP規範的主要編寫者之一。 他在論文中提到："我這篇文章的寫做目的，就是想在符合架構原理的前提下，理解和評估以網絡爲基礎的應用軟件的架構設計，獲得一個功能強、性能好、適宜通訊的架構。REST指的是一組架構約束條件和原則。" 若是一個架構符合REST的約束條件和原則，咱們就稱它爲RESTful架構。

　　REST自己並無創造新的技術、組件或服務，而隱藏在RESTful背後的理念就是使用Web的現有特徵和能力， 更好地使用現有Web標準中的一些準則和約束。雖然REST自己受Web技術的影響很深， 可是理論上REST架構風格並非綁定在HTTP上，只不過目前HTTP是惟一與REST相關的實例。 因此咱們這裏描述的REST也是經過HTTP實現的REST。

　　REST全稱是表述性狀態轉移，那究竟指的是什麼的表述? 其實指的就是資源。任何事物，只要有被引用到的必要，它就是一個資源。資源能夠是實體(例如手機號碼)，也能夠只是一個抽象概念(例如價值) 。

　　

　　要讓一個資源能夠被識別，須要有個惟一標識，在Web中這個惟一標識就是URI(Uniform Resource Identifier)。

　　URI既能夠當作是資源的地址，也能夠當作是資源的名稱。若是某些信息沒有使用URI來表示，那它就不能算是一個資源， 只能算是資源的一些信息而已。URI的設計應該遵循可尋址性原則，具備自描述性，須要在形式上給人以直覺上的關聯。這裏以github網站爲例，給出一些還算不錯的URI：

• https://github.com/git
• https://github.com/git/git
• https://github.com/git/git/blob/master/block-sha1/sha1.h
• https://github.com/git/git/commit/e3af72cdafab5993d18fae056f87e1d675913d08
• https://github.com/git/git/pulls
• https://github.com/git/git/pulls?state=closed
• https://github.com/git/git/compare/master…next

設計規範

　　一.url設計

　　1.1動詞加賓語

　　RESTful 的核心思想就是，客戶端發出的數據操做指令都是"動詞 + 賓語"的結構。好比，GET /articles這個命令，GET是動詞，/articles是賓語。

　　動詞一般就是五種 HTTP 方法，對應 CRUD 操做。

• GET：讀取（Read）
• POST：新建（Create）
• PUT：更新（Update）
• PATCH：更新（Update），一般是部分更新
• DELETE：刪除（Delete）

　　根據 HTTP 規範，動詞一概大寫。

　　1.2動詞的覆蓋

　　有些客戶端只能使用GET和POST這兩種方法。服務器必須接受POST模擬其餘三個方法（PUT、PATCH、DELETE）。

　　這時，客戶端發出的 HTTP 請求，要加上X-HTTP-Method-Override屬性，告訴服務器應該使用哪個動詞，覆蓋POST方法。

POST /api/Person/4 HTTP/1.1  
X-HTTP-Method-Override: PUT 

　　上面代碼中，X-HTTP-Method-Override指定本次請求的方法是PUT，而不是POST。

　　1.3賓語必須是名詞

　　賓語就是 API 的 URL，是 HTTP 動詞做用的對象。它應該是名詞，不能是動詞。好比，/articles這個 URL 就是正確的，而下面的 URL 不是名詞，因此都是錯誤的。

• /getAllCars
• /createNewCar
• /deleteAllRedCars

　　1.4複數url

　　既然 URL 是名詞，那麼應該使用複數，仍是單數？

　　這沒有統一的規定，可是常見的操做是讀取一個集合，好比GET /articles（讀取全部文章），這裏明顯應該是複數。

　　爲了統一塊兒見，建議都使用複數 URL，好比GET /articles/2要好於GET /article/2。

　　

　　1.5 避免多級 URL

　　常見的狀況是，資源須要多級分類，所以很容易寫出多級的 URL，好比獲取某個做者的某一類文章。

GET /authors/12/categories/2

　　這種 URL 不利於擴展，語義也不明確，每每要想一會，才能明白含義。

　　更好的作法是，除了第一級，其餘級別都用查詢字符串表達。

GET /authors/12?categories=2

　　下面是另外一個例子，查詢已發佈的文章。你可能會設計成下面的 URL。

GET /articles/published

　　查詢字符串的寫法明顯更好。

GET /articles?published=true

　　二.狀態碼

　　

　　2.1 狀態碼必須精確

　　客戶端的每一次請求，服務器都必須給出迴應。迴應包括 HTTP 狀態碼和數據兩部分。

　　HTTP 狀態碼就是一個三位數，分紅五個類別。

• 1xx：相關信息
• 2xx：操做成功
• 3xx：重定向
• 4xx：客戶端錯誤
• 5xx：服務器錯誤

　　這五大類總共包含100多種狀態碼，覆蓋了絕大部分可能遇到的狀況。每一種狀態碼都有標準的（或者約定的）解釋，客戶端只需查看狀態碼，就能夠判斷出發生了什麼狀況，因此服務器應該返回儘量精確的狀態碼。

　　API 不須要1xx狀態碼，下面介紹其餘四類狀態碼的精確含義。

　　2.2 2xx 狀態碼

　　200狀態碼錶示操做成功，可是不一樣的方法能夠返回更精確的狀態碼。

• GET: 200 OK
• POST: 201 Created
• PUT: 200 OK
• PATCH: 200 OK
• DELETE: 204 No Content

　　上面代碼中，POST返回201狀態碼，表示生成了新的資源；DELETE返回204狀態碼，表示資源已經不存在。

　　此外，202 Accepted狀態碼錶示服務器已經收到請求，但還未進行處理，會在將來再處理，一般用於異步操做。下面是一個例子。

HTTP/1.1 202 Accepted

{
  "task": {
    "href": "/api/company/job-management/jobs/2130040",
    "id": "2130040"
  }
}

　　2.3 3xx 狀態碼

　　API 用不到301狀態碼（永久重定向）和302狀態碼（暫時重定向，307也是這個含義），由於它們能夠由應用級別返回，瀏覽器會直接跳轉，API 級別能夠不考慮這兩種狀況。

　　API 用到的3xx狀態碼，主要是303 See Other，表示參考另外一個 URL。它與302和307的含義同樣，也是"暫時重定向"，區別在於302和307用於GET請求，而303用於POST、PUT和DELETE請求。收到303之後，瀏覽器不會自動跳轉，而會讓用戶本身決定下一步怎麼辦。下面是一個例子。

HTTP/1.1 303 See Other
Location: /api/orders/12345 

　　2.4 4xx 狀態碼

　　4xx狀態碼錶示客戶端錯誤，主要有下面幾種。

　　400 Bad Request：服務器不理解客戶端的請求，未作任何處理。

　　401 Unauthorized：用戶未提供身份驗證憑據，或者沒有經過身份驗證。

　　403 Forbidden：用戶經過了身份驗證，可是不具備訪問資源所需的權限。

　　404 Not Found：所請求的資源不存在，或不可用。

　　405 Method Not Allowed：用戶已經經過身份驗證，可是所用的 HTTP 方法不在他的權限以內。

　　410 Gone：所請求的資源已從這個地址轉移，再也不可用。

　　415 Unsupported Media Type：客戶端要求的返回格式不支持。好比，API 只能返回 JSON 格式，可是客戶端要求返回 XML 格式。

　　422 Unprocessable Entity ：客戶端上傳的附件沒法處理，致使請求失敗。

　　429 Too Many Requests：客戶端的請求次數超過限額。

　　2.5 5xx 狀態碼

　　5xx狀態碼錶示服務端錯誤。通常來講，API 不會向用戶透露服務器的詳細信息，因此只要兩個狀態碼就夠了。

　　500 Internal Server Error：客戶端請求有效，服務器處理時發生了意外。

　　503 Service Unavailable：服務器沒法處理請求，通常用於網站維護狀態。

　　3、服務器迴應

　　3.1 不要返回純本文

　　API 返回的數據格式，不該該是純文本，而應該是一個 JSON 對象，由於這樣才能返回標準的結構化數據。因此，服務器迴應的 HTTP 頭的Content-Type屬性要設爲application/json。

　　客戶端請求時，也要明確告訴服務器，能夠接受 JSON 格式，即請求的 HTTP 頭的ACCEPT屬性也要設成application/json。下面是一個例子。

GET /orders/2 HTTP/1.1 
Accept: application/json 

　　3.2 發生錯誤時，不要返回 200 狀態碼

　　有一種不恰當的作法是，即便發生錯誤，也返回200狀態碼，把錯誤信息放在數據體裏面，就像下面這樣。

HTTP/1.1 200 OK
Content-Type: application/json { "status": "failure", "data": { "error": "Expected at least two items in list." } } 

　　上面代碼中，解析數據體之後，才能得知操做失敗。

　　這張作法實際上取消了狀態碼，這是徹底不可取的。正確的作法是，狀態碼反映發生的錯誤，具體的錯誤信息放在數據體裏面返回。下面是一個例子。

HTTP/1.1 400 Bad Request
Content-Type: application/json { "error": "Invalid payoad.", "detail": { "surname": "This field is required." } } 

　　3.3 提供連接

　　API 的使用者未必知道，URL 是怎麼設計的。一個解決方法就是，在迴應中，給出相關連接，便於下一步操做。這樣的話，用戶只要記住一個 URL，就能夠發現其餘的 URL。這種方法叫作 HATEOAS。

　　舉例來講，GitHub 的 API 都在 api.github.com 這個域名。訪問它，就能夠獲得其餘 URL。

{
  ...
  "feeds_url": "https://api.github.com/feeds",
  "followers_url": "https://api.github.com/user/followers",
  "following_url": "https://api.github.com/user/following{/target}",
  "gists_url": "https://api.github.com/gists{/gist_id}",
  "hub_url": "https://api.github.com/hub",
  ...
}

　　上面的迴應中，挑一個 URL 訪問，又能夠獲得別的 URL。對於用戶來講，不須要記住 URL 設計，只要從 api.github.com 一步步查找就能夠了。

　　HATEOAS 的格式沒有統一規定，上面例子中，GitHub 將它們與其餘屬性放在一塊兒。更好的作法應該是，將相關連接與其餘屬性分開。

HTTP/1.1 200 OK
Content-Type: application/json { "status": "In progress", "links": {[ { "rel":"cancel", "method": "delete", "href":"/api/status/12345" } , { "rel":"edit", "method": "put", "href":"/api/status/12345" } ]} } 

　　4、參考連接

• RESTful API Design: 13 Best Practices to Make Your Users Happy, by Florimond Manca
• API design, by MicroSoft Azure

• RESTful API 最佳實踐,阮一峯的網絡日誌

　　（完）