一、背景與基礎概念

Web 應用程序最重要的 REST 原則是，客户端和服務器之間的交互在請求之間是無狀態的。從客户端到服務器的每個請求都必須包含理解請求所必需的信息。

  • 資源（resource）：網絡上的一個實體或者説是一個具體信息，可以是一段文本、一張圖片、一首歌曲、一種服務。
  • 統一資源定位符（URI，Universal Resource Identifier）：一個資源的識別符或者説是一個地址，通過URI你可以定位到特定的資源。要獲取這個資源，需要訪問它的URI，因此，URI就成了每一個資源的地址或獨一無二的識別符。
  • 狀態轉換（State Transfer）: 所有資源都共享統一的接口，以便在客户端和服務器之間傳輸狀態。客户端與服務器互動的過程，通常涉及到服務器端數據和狀態的變化過程，比如文件被修改，訪問數量增加等。使用的是標準的 HTTP 方法，Http標準中定義的最主要四個動詞：GET、POST、PUT、DELETE。它們分別對應四種基本操作：
      - GET： 用來獲取資源
      - POST： 用來新建資源
      - PUT： 用來更新資源
      - DELETE： 用來刪除資源
  • Hypermedia 是應用程序狀態的引擎，資源表示通過超鏈接互聯。

二、RESTful API應遵循的原則

1、協議(Protocol)
  API與用户的通信協議，儘量使用HTTPs協議。HTTPs協議的所有信息都是加密傳播，第三方無法竊聽，具有校驗機制，一旦被篡改，通信雙方會立刻發現，配備身份證書，防止身份被冒充。

2、域名(ROOT URL)
  應該儘量將API部署在專用域名之下。
  https://api.example.com   如果確定API很簡單，不會有進一步擴展，可以考慮放在主域名下。
  https://example.org/api/

3、版本(Versioning)
應該將API的版本號放入URL。

4、路徑(EndPoints)
路徑表示API的具體網址URL。在RESTful架構中，每個URL代表一種資源（resource），所以網址中不能有動詞，只能有名詞，而且所用的名詞往往與代表的對象名稱對應。一般來説，某一同種記錄的”集合”（collection），所以API中的名詞也應該使用複數。

5、HTTP動詞(HTTP Verbs)
  對於資源的具體操作類型，由HTTP動詞表示。常用的HTTP動詞有下面五個：

  • GET（SELECT）：從服務器取出資源（一項或多項）
  • POST（CREATE）：在服務器新建一個資源。
  • PUT（UPDATE）：在服務器更新資源（客户端提供改變後的完整資源）。
  • PATCH（UPDATE）：在服務器更新資源（客户端提供改變的屬性）。
  • DELETE（DELETE）：從服務器刪除資源。
      還有兩個不常用的HTTP動詞。
  • HEAD：獲取資源的元數據。
  • OPTIONS：獲取信息，關於資源的哪些屬性是客户端可以改變的。
    注：Get方法和查詢參數不應該涉及狀態改變。使用PUT, POST 和DELETE方法而不是 GET 方法來改變狀態。

6、過濾信息（Filtering）
如果記錄數量很多，服務器不可能都將它們返回給用户。API應該提供參數，過濾返回結果。為集合提供過濾、排序、選擇和分頁等功能。
下面是一些常見的參數。

  • ?limit=10：指定返回記錄的數量
  • ?offset=10：指定返回記錄的開始位置。
  • ?pageNumber=2&perSize=100：指定第幾頁，以及每頁的記錄數。
  • ?sortby=name&order=asc：指定返回結果按照哪個屬性排序，以及排序順序。
  • ?animal_type_id=1：指定篩選條件

7、狀態碼（Status Codes）
服務器向用户返回的狀態碼和提示信息.

8、錯誤處理（Error handling）
如果狀態碼是4xx，就應該向用户返回出錯信息。儘量使用詳細的錯誤包裝信息：

{
  "errors": [
   {
    "userMessage": "Sorry, the requested resource does not exist",
    "internalMessage": "No car found in the database",
    "code": 4xx,
    "more info": "http://dev.example.com/api/v1/errors/12345"
   }
  ]
}

9、返回結果（Response）
服務器返回的數據格式，應該儘量使用JSON，避免使用XML。針對不同操作，服務器向用户返回的結果應該符合以下規範。

  • GET /collection：返回資源對象的列表（數組）
  • GET /collection/resource：返回單個資源對象
  • POST /collection：返回新生成的資源對象
  • PUT /collection/resource：返回完整的資源對象
  • PATCH /collection/resource：返回完整的資源對象
  • DELETE /collection/resource：返回一個空文檔

10、使用HATEOAS的Hypermedia API
RESTful API最好使用Hypermedia as the Engine of Application State（超媒體作為應用狀態的引擎），即返回結果中提供鏈接，連向其他API方法，超文本鏈接可以建立更好的文本瀏覽，使得用户不查文檔，也知道下一步應該做什麼。

11、認證（Authentication）
API的身份認證儘量使用OAuth 2.0框架。

三、Swagger API標準

API的文檔管理和信息描述，將使用Swagger進行。
  Swagger是一個規範和完整的框架，用於生成、描述、調用和可視化RESTful風格的Web服務。Swagger的目標是對REST API定義一個標準的和語言無關的接口，可讓人和計算機無需訪問源碼、文檔或網絡流量監測就可以發現和理解服務的能力。