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

2021-12-21 方志朋
1.什麼是REST

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

2.URI規範

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的圖書。

3.正確使用method

get -只用做資源的讀取。

post-通過用作創建一個新的資源。

delete-通過用作資源的刪除。

put -通過用作更新資源或者創建資源

head-只獲取某個資源的頭部信息。

比如 豆瓣圖書api：

namemethodapi獲取圖書信息get/v2/book/:id用戶收藏某本圖書post/v2/book/:id/collection用戶修改對某本圖書的收藏put/v2/book/:id/collection用戶刪除對某個圖書的收藏delete/v2/book/:id/collection

另外，在一些不符合curd的情況下，使用　post。

把動作轉換成資源

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

4.選擇合適的狀態碼

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

2xx: 請求正常處理並返回

3xx: 重定向

4xx: 客戶端請求有錯誤

5xx: 服務端請求有錯誤

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

狀態碼含義說明200ok請求成功201created創建成功202accepted更新成功400bad request請求不存在401unauthorized未授權403forbidden禁止訪問404not found資源不存在500internal server error內部錯誤5.使用通用的錯誤碼

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

錯誤碼錯誤信息含義999unknow_v2_error未知錯誤1000need_permission需要權限1001uri_not_found資源不存在…….…

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

6. 安全

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

7.api文檔

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

8.參考資料

本文參考了以下的資料:

豆瓣api

理解restful架構

restful introduction

跟著github學習restful api設計

REST接口設計規範

restful api 設計指南

相關焦點

  • RESTful API 介紹及設計
    通常用HTTP的方法來操作。誰來操作誰呢？客戶端對服務度資源的操作具備上面的這幾種要素，就是RESTful架構。RESTful是一種設計風格。四：RESTful API實踐API設計RESTful API 是基於REST架構設計理念之下利用http協議來描述接口操作接口。
  • 如何理解RESTful API設計規範?
    在很久以前，工作時間長的同學肯定經歷過使用velocity語法來編寫html模板代碼，也就是說我們的前端頁面放在伺服器端那邊進行編譯的，更準確的可以理解為 "前後端沒有進行分離"。因此為了解決這個問題慢慢就出現了前後端分離的思想: 即後端負責數據接口, 前端負責數據渲染, 前端只需要請求下api接口拿到數據，然後再將數據顯示出來。因此後端開發人員需要設計api接口，因此為了統一規範: 社區就出現了 RESTful API 規範。
  • Restful API設計規範
    在當前流行的前後端分離架構，人們發現原來這套用於超文本傳輸的協議是如此適合用於設計基於網際網路的api接口，基於http動詞以及標準的http status返回信息，能夠非常好地描述api的特性，並且可讀性非常好。
  • RESTful API 設計指南
    這導致API構架的流行，甚至出現」API First」的設計思想。RESTful API是目前比較成熟的一套網際網路應用程式的API設計理論。我以前寫過一篇《理解RESTful架構》，探討如何理解這個概念。今天，我將介紹RESTful API的設計細節，探討如何設計一套合理、好用的API。我的主要參考了兩篇文章（1，2）。
  • 理解 RESTful API 設計規範
    它是基於HTTP、URI、XML、JSON等標準和協議，支持輕量級、跨平臺、跨語言的架構設計。一、理解為什麼要使用RESTful API設計規範？http請求本身是無狀態的，它是基於 client-server 架構的，客戶端向伺服器端發的每一次請求都必須帶有充分的信息能夠讓伺服器端識別到，請求的一些信息通常會包含在URL的查詢參數中或header中，伺服器端能夠根據請求的各種參數, 不需要保存客戶端的狀態, 直接將數據返回給客戶端。無狀態的優點是：可以大大提高伺服器端的健狀性和可擴展性。客戶端可以通過token來標識會話狀態。
  • 理解RESTful API 架構設計規範與實踐
    在通常的 API 設計中，直接使用 URL 來標示應用系統中的資源。https://www.sample.com/api/shops/10083 - 編號10083店鋪的基本信息https://www.sample.com/api/users/2372/orders - 編號2372用戶的所有訂單信息在標準的 REST 規範觀點中，通常會要求將資源 shop 加上複數形式 s 表示多個資源。
  • 深入理解 RESTful Api 架構
    REST 和 HTTP/1.1 Roy Fielding （Apache HTTP 伺服器的核心開發者，Apache 軟體基金會的合作創始人，HTTP/1.1 協議專家組的負責人）總結了一套理論框架，然後使用這套理論框架中的指導原則，來指導HTTP/1.1協議的設計方向。
  • 深入理解什麼是RESTful API ?
    網際網路的興起，使得這兩個領域開始融合，** 現在我們必須考慮，如何開發在網際網路環境中使用的軟體。**RESTful架構，就是目前最流行的一種網際網路軟體架構。它結構清晰、符合標準、易於理解、擴展方便，所以正得到越來越多網站的採用。　　但是，到底什麼是RESTful架構，並不是一個容易說清楚的問題。下面，我就談談我理解的RESTful架構。
  • RESTful架構和RESTful API設計總結
    他的這篇博士論文可以說對網際網路的軟體設計產生了深遠的影響。但是從字面上理解REST(Representational State Transfer, 表現層狀態轉移)是非常抽象的。State Transfer 狀態轉移通過http動詞來實現資源的狀態轉移，用GET來請求資源，用POST來新建資源，用PUT來更新資源，用DELETE來刪除資源。簡明扼要的總結REST：RESTful API設計總結隨著近年來移動網際網路的發展，各種客戶端出不窮：Web，IOS，Android。
  • Laravel 開發 RESTful API 的一些心得
    大方面，會涉及到給別人用的使用OAuth，自己使用的用token就足夠了設計最初，最好在路由加個版本號，方便以後擴展。function () {    // more});如果前端想跨域，請使用這個很方便的包barryvdh/laravel-cors(https://github.com/barryvdh/laravel-cors)一個簡單的接口示例：驗證API 開發總會離不開驗證，這裡推薦使用jwt-auth，1.0 快要來了
  • RESTful API 編寫指南
    URL RulesRESTful API 是寫給開發者來消費的，其命名和結構需要有意義。因此，在設計和編寫URL時，要符合一些規範。Url rules 可以單獨寫一篇博客來詳細闡述，本文只列出一些關鍵點。
  • RESTful API 設計規範
    為了更好的討論規範帶來的爭議及問題，現已把該文檔整理並開源到 github (https://github.com/godruoyi/restful-api-specification)，關於大家補充及提 issue。
  • axios中restful api的使用
    1引子在前端發送網絡請求的時候，現在最經常使用的是axios, 而axios的api中我們（確切說是我）最常用的就是post，而其他api很少有用到的場景。最近在做一個簡單需求（增刪改查）的時候，後端給的接口是restful風格的。看看吧：嗯，看到上圖我還沒感覺到什麼，接著看：
  • 良好的 API 設計指南-RESTful API
    如果想讓服務端的價值更好的體現出來，就要好好設計API。通過這些API，你的服務/核心程序將有可能成為其他項目所依賴的平臺；你提供的API越易用，就會有越多人願意使用它。規劃API的展示形式可能比你想像的要簡單，首先要確定你的數據是如何設計以及核心程序是如何工作的。
  • 如何設計一個開放平臺openapi?
    從2012年開始網際網路金融公司也開始上線開放平臺系統，支付寶在2012年10月上線了支付寶開放平臺，開放了支付類相關的api，筆者當時在銀行，我們銀行也在10月份開始實施開放平臺的設計和開發工作，一開始對於開放平臺的理解還不是很深入，只能上支付寶的開放平臺深入「學習」下，後來經過半年左右的開發我們的銀行開放平臺在13年終於上線了，在當時的國內銀行業也是第一家開放api的銀行，後來不斷迭代優化前前後後一共做了
  • RESTFUL API 安全設計指南
    資源可以用 URI 來表示。客戶端使用 HTTP 協議定義的方法來發送請求到這些 URIs，當然可能會導致這些被訪問的」資源「狀態的改變。2.2 API KEYAPI Key就是經過用戶身份認證之後服務端給客戶端分配一個API Key，類似：http://example.com/api?key=dfkaj134,一般的處理流程如下：一個簡單的設計示例如下：client端：
  • RESTful API如何進行版本控制
    本文將幫助您理解為什麼需要版本控制，以及如何對REST API進行版本控制。我們將討論4種版本控制的方法，並比較不同的方法。您將學到為什麼我們需要對RESTful API 進行版本控制?讓我們來看看創建相同服務版本的4種不同方法。
  • 教你 10 分鐘構建一套 RESTful API 服務( 中 )
    if __name__ == '__main__':    app.run()從 flask_restful 文件中導入 Api、Resource 兩個類，使用上面的 app 對象，構建一個 api 對象，接著準備一個列表數據from flask_restful import Api,Resourceapp
  • RESTful API 設計學習筆記
    舉例來說，有一個 API 提供動物園（zoo）的信息，還包括各種動物和僱員的信息，則它的路徑應該設計成這樣：https://api.example.com/v1/zooshttps://api.example.com/v1/animalshttps://api.example.com/v1/employeesURI 中需要注意的幾點
  • API 接口規範
    整體規範建議採用RESTful 方式來實施。協議API 與客戶端通訊協議主要包含 http 和 https，建議使用 https 確保交互數據的傳輸安全。域名應該儘量將API部署在專用域名之下。舉例來說，有一個API提供動物園（zoo）的信息，還包括各種動物和僱員的信息，則它的路徑應該設計成下面這樣。