blog height -s inf pos git col 也好 img

1、什麽是RESTful風格的API

REST，即Representational State Transfer，可以理解為“（資源的）表現層狀態轉化”。

在網絡上，我們通過瀏覽器輸入url，來訪問和獲取到所需要的資源。這裏的url，是對資源位置的定位描述，其實也是一種資源的具體呈現的方式，即這裏所說的“表現層”。我們訪問資源的過程涉及到數據和狀態的變化，“建立在表現層（url）基礎上使資源狀態發生變化”，也即“表現層狀態轉化（REST）”了。
符合REST規範的API，則稱之為RESTful風格的API，再大白話一點，能讓我們“通過API接口名稱就能明白它的作用”，它優雅、規範、易懂，省去了許多無意義的溝通和文檔。核心規範是什麽呢？使用HTTP協議中的四種不同請求方式，來代表四種不同的動詞操作：GET用來獲取資源；POST用來新建資源；PUT用來更新資源；DELETE用來刪除資源。
具體一點來說，RESTful API有如下特點：

• 基於“資源”，數據也好，服務也好，在RESTful設計中一切都是資源
• 每個URL表示一種資源
• URL語義清晰明確，不出現動詞，只有名詞（操作的動詞是通過請求方式來表示）
• 使用HTTP的 POST、DELETE、PUT、GET 來表示對資源的增刪改查
• 盡量使用JSON而不是XML
• 應該將API的版本號放入URL

舉例來說，某API提供動物園（zoo）系統相關信息，則RESTful的API風格如下：

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

再具體一點：

• GET /zoos：列出所有動物園
• POST /zoos：新建一個動物園
• GET /zoos/ID：獲取某個指定動物園的信息
• PUT /zoos/ID：更新某個指定動物園的信息
• GET /zoos/ID/animals：列出某個指定動物園的所有動物
• DELETE /zoos/ID/animals/ID：刪除某個指定動物園的指定動物

API同時也可以提供一些參數，用來過濾返回結果，常見參數如下：

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

上面來一個鮮活的例子，豆瓣圖書相關的開發API：
先看看這個鏈接，是什麽作用？再試試直接訪問（GET方式），返回的內容是什麽？https://api.douban.com/v2/book/1220563

2、RESTful什麽時候好用

對於開放的API，豆瓣、新浪微博、GitHub，好用，非常合適；對於內部開發，不好用。

基於資源型的RESTful API 接口粒度和返回結果過於的“粗”，它通常返回的都是完整的數據模型，這對於客戶端非常不友好。但開放API之所以開放，就是因為它不知道你到底需要什麽返回結果，既然不知道，那麽我幹脆都返回給你。這樣的好處是通用，但客戶端不好處理。你只需要一個字段，服務器卻丟給你十幾個，作為客戶端開發者你怎麽想？
內部開發由於需求非常明確，通常來說服務器是不應該簡單粗暴的直接甩資源實體給客戶端的。那RESTful API就不能接入到內部開發嗎？當然不是，我們需要靈活一些借鑒RESTFul中的優點，來設計我們的內部API。那麽如何簡化，就需要自己去琢磨和體會了。

3、參考鏈接

• REST與RESTFul API最佳實踐
  
• 理解RESTful架構
  
• RESTful API 設計指南
  
• 我所認為的RESTful API最佳實踐
  

[01] 淺談RESTful風格的API