RESTful規範

RESTful規範

RESTful

• 是一種軟件的架構風格，設計風格，爲客戶端和服務端的交互提供一組軟件原則和約束條件
• 若是一個架構符合REST的約束和原則，咱們就稱它爲RESTful架構
• REST是Representational State Transfer的簡稱，中文翻譯爲「表徵狀態轉移」

restfull的規範

• 前言： 這只是一種規範，咱們要儘可能的知足，當需求和規範有衝突的時候，咱們能夠不遵照規範

一 協議

• API與用戶的通訊協議，老是使用https協議

二 域名

• 應該儘可能的將API部署在專用的域名之下

  https://api.example.com

  注意：這種狀況會存在跨域的問題

• 若是肯定API很簡單，不會進一步擴展，能夠考慮放在主域名下

  https://example.org/api/

  這樣就不會存在跨域問題

三 版本（Versioning）

• 應該將API的版本號放入URL

  https://api.example.com/v1/

• 還有一種是放在請求頭內

四 路徑

• 在 RESTful框架中，每一個網址都是一種資源，因此咱們要盡最大可能的使用名詞，能夠是複數

  https://api.example.com/v1/zoos
  https://api.example.com/v1/animals
  https://api.example.com/v1/employees

五 method方法

• 對於資源的具體操做類型，根據method的不一樣，進行不一樣的操做

  GET      ：從服務器取出資源（一項或多項）
  POST    ：在服務器新建一個資源
  PUT      ：在服務器更新資源（客戶端提供改變後的完整資源）
  PATCH  ：在服務器更新資源（客戶端提供改變的屬性）
  DELETE ：從服務器刪除資源

• 實例

  GET /zoos：列出全部動物園
  POST /zoos：新建一個動物園
  GET /zoos/ID：獲取某個指定動物園的信息
  PUT /zoos/ID：更新某個指定動物園的信息（提供該動物園的所有信息）
  PATCH /zoos/ID：更新某個指定動物園的信息（提供該動物園的部分信息）
  DELETE /zoos/ID：刪除某個動物園
  GET /zoos/ID/animals：列出某個指定動物園的全部動物
  DELETE /zoos/ID/animals/ID：刪除某個指定動物園的指定動物

六 過濾信息（Filtering）

• 經過在url上傳參的形式傳遞搜索條件

  https://api.example.com/v1/zoos?limit=10：指定返回記錄的數量
  https://api.example.com/v1/zoos?offset=10：指定返回記錄的開始位置
  https://api.example.com/v1/zoos?page=2&per_page=100：指定第幾頁，以及每頁的記錄數
  https://api.example.com/v1/zoos?sortby=name&order=asc：指定返回結果按照哪一個屬性排序，以及排序順序
  https://api.example.com/v1/zoos?animal_type_id=1：指定篩選條件

七 狀態碼

• 服務器向用戶返回的狀態碼和提示信息

八 錯誤處理

• 返回值攜帶錯誤的信息

  狀態碼爲4xx是，應該返回錯誤信息

  {
      ``error: ``"Invalid API key"
  }

九 返回結果

• 針對不一樣的操做，服務器向於洪返回的結果應該符合如下規範

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

十 Hypermedia API

• RESTful API最好作到Hypermedia，即返回結果中提供連接，連向其餘API方法，使得用戶不查文檔，也知道下一步應該作什麼。

  {``"link"``: {
    ``"rel"``:   ``"collection https://www.example.com/zoos"``,
    ``"href"``:  ``"https://api.example.com/zoos"``,
    ``"title"``: ``"List of zoos"``,
    ``"type"``:  ``"application/vnd.yourformat+json"
  }}