我是如何根據豆瓣api來理解Restful API設計的

1.什麼是REST

REST全稱是Representational State Transfer,表述狀態轉移的意思。它是在Roy Fielding博士論文首次提出。REST本身沒有創造新的技術、組件或服務，它的理念就是在現有的技術之上，更好的使用現有的 web規範。用REST規範的web伺服器，能夠更好的展現資源，客戶端能夠更好的使用資源。每個資源都由URI/ID標識。REST本身跟http無關，但是目前http是與它相關的唯一實例。REST有著優雅、簡潔的特性，本文是根據豆瓣api來談談自己對restful的一些理解。

2.URI規範

• URI(Uniform Resource Identifiers) 統一資源標示符
• URL(Uniform Resource Locator) 統一資源定位符

URI 的格式：

URI的格式定義如下： 
URI = scheme "://" authority "/" path [ "?" query ] [ "#" fragment ]

• uri代表的是一種資源，要做到優雅、簡潔。
• 最好在api地址標明版本

比如

https://api.douban.com/v2

• 關於分隔符「／」，比如：

"/"分隔符一般用來對資源層級的劃分,比如：
https://api.douban.com/v2/book/1220562
表述了豆瓣api，version2下的圖書倉庫下的編號為1220562的圖書。

• URI儘量使用「-」代替下劃線「_「。
• URI統一使用小寫字母
• URI不包含文件擴展名
• 使用？用來過濾資源，比如？limit=10 :指定返回10條記錄。
• 不使用無意義的字符串、數字，要做到簡潔。

3.正確使用method

• get -只用做資源的讀取。
• post-通過用作創建一個新的資源。
• delete-通過用作資源的刪除。
• put -通過用作更新資源或者創建資源
• head-只獲取某個資源的頭部信息。

比如 豆瓣圖書api：

• 另外，在一些不符合curd的情況下，使用　post。
• 把動作轉換成資源
• 比如，上述接口中，用戶收藏某本書對外暴露的接口是」/v2/book/:id/collection」,收藏動作通過post方法來展現，而不直接寫著api中，collection 「收藏」，名次，動作直接轉換成了資源。

4.選擇合適的狀態碼

http請求需要返回狀態碼，約定俗成的狀態碼能夠幫助開發團隊提高溝通效率。

• 2xx: 請求正常處理並返回
• 3xx: 重定向
• 4xx: 客戶端請求有錯誤
• 5xx: 服務端請求有錯誤

比如豆瓣api返回的狀態碼說明：

5.使用通用的錯誤碼

通用錯誤碼，具體產品由具體產品api給出。比如豆瓣api:

太多了，只列出幾條，具體見豆瓣 api。

6. 安全

這部分內容不屬於這篇文章，但是稍微說明下：

• 使用https
• 使用jwt驗證
• 使用參數簽名，防止參數被篡改。
• 使用權限驗證，shiro ,或者自己建資料庫（用戶、角色、權限）

7.api文檔

接口文檔的編寫至關重要，最好是寫一個在線接口文檔。接口文檔能夠方便團隊查閱，減少不必要的溝通。如果對外公開api，api文檔的質量直接反應了一個公司的技術水平，甚至一個公司的文化氣質。

8.參考資料

本文參考了以下的資料:

豆瓣api

理解restful架構

restful introduction

跟著github學習restful api設計

REST接口設計規範

restful api 設計指南

文章出處：https://dwz.cn/itlp4AkW

作者：方誌朋