[01] 淺談RESTful風格的API
阿新 • • 發佈:2018-01-23
blog height -s inf pos git col 也好 img
在網絡上,我們通過瀏覽器輸入url,來訪問和獲取到所需要的資源。這裏的url,是對資源位置的定位描述,其實也是一種資源的具體呈現的方式,即這裏所說的“表現層”。我們訪問資源的過程涉及到數據和狀態的變化,“建立在表現層(url)基礎上使資源狀態發生變化”,也即“表現層狀態轉化(REST)”了。
符合REST規範的API,則稱之為RESTful風格的API,再大白話一點,能讓我們“通過API接口名稱就能明白它的作用”,它優雅、規範、易懂,省去了許多無意義的溝通和文檔。核心規範是什麽呢?使用HTTP協議中的四種不同請求方式,來代表四種不同的動詞操作:GET用來獲取資源;POST用來新建資源;PUT用來更新資源;DELETE用來刪除資源。
具體一點來說,RESTful API有如下特點:
舉例來說,某API提供動物園(zoo)系統相關信息,則RESTful的API風格如下:
再具體一點:
API同時也可以提供一些參數,用來過濾返回結果,常見參數如下:
上面來一個鮮活的例子,豆瓣圖書相關的開發API:![技術分享圖片](http://image.bubuko.com/info/201801/20180122234829697360.png)
先看看這個鏈接,是什麽作用?再試試直接訪問(GET方式),返回的內容是什麽?https://api.douban.com/v2/book/1220563
基於資源型的RESTful API 接口粒度和返回結果過於的“粗”,它通常返回的都是完整的數據模型,這對於客戶端非常不友好。但開放API之所以開放,就是因為它不知道你到底需要什麽返回結果,既然不知道,那麽我幹脆都返回給你。這樣的好處是通用,但客戶端不好處理。你只需要一個字段,服務器卻丟給你十幾個,作為客戶端開發者你怎麽想?
內部開發由於需求非常明確,通常來說服務器是不應該簡單粗暴的直接甩資源實體給客戶端的。那RESTful API就不能接入到內部開發嗎?當然不是,我們需要靈活一些借鑒RESTFul中的優點,來設計我們的內部API。那麽如何簡化,就需要自己去琢磨和體會了。
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:
![技術分享圖片](http://image.bubuko.com/info/201801/20180122234829697360.png)
先看看這個鏈接,是什麽作用?再試試直接訪問(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