RESTful API - 介紹
目錄
- RESTful API 介紹
- RESTful介紹
- RESTful API設計指南
- API與用戶的通信協議
- 域名
- 版本(Versioning)
- 路徑(Endpoint)
- 瀏覽器請求方式(method)
- 過濾信息(Filtering)
- 狀態碼
- 錯誤處理(Error handling)
- 返回結果
- Hypermedia API
- 其他
RESTful API 介紹
RESTful介紹
REST是Representational StateTransfer的簡稱,中文翻譯為"表征狀態轉移"或"表現層狀態轉化",本身與技術無關, 其代表的是一種軟件架構風格,統一的架構開發風格,會減少開發者之間不少障礙.
RESTful API設計指南
API與用戶的通信協議
[推薦閱讀>>][2]
[2]: http://www.ruanyifeng.com/blog/2014/02/ssl_tls.html
域名
API部署在專用域名之下
https://api.example.com
API很簡單不會有進一步擴展的時候可以放在主域名下
https://example.org/aip/
版本(Versioning)
API版本號放入到URl
https://api.example.com/v1/
API版本HTTP頭信息中
路徑(Endpoint)
- 只能有名詞
- 與數據庫的表格名對應
名詞使用負數
https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees
瀏覽器請求方式(method)
GET: 從資源覽器取出資源(一項或多項)
POST: 在瀏覽器新建一個資源
PUT: 在服務器更新資源(客戶端提供改變後的完整資源)
PATCH: 在服務器更新資源(客戶端提供改變的屬性)
DELETE: 從服務器刪除資源
過濾信息(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:指定篩選條件
狀態碼
1xx:表示信息類
2xx:成功類
3xx:重定向
4xx:客戶端錯誤
5xx:內部服務器錯誤
[狀態碼大全>>][2]
[2]: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
錯誤處理(Error handling)
狀態碼是4xx時,返回錯誤信息,error當做key
{
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"
}}
其他
API的身份認證應該使用[OAuth 2.0框架>>][2]
[2]: http://www.ruanyifeng.com/blog/2014/05/oauth_2_0.html服務器返回的數據格式, 應該盡量使用JSON, 避免使用XML.
RESTful API - 介紹