RESTful 規范


在做的前幾個小網站,往往過程是,后端在編寫的時候需要前端提供靜態文件的支持,所以往往,前端后端相互依賴,相互等待。而前后端分離使得前后端解耦,只要定義規范的接口(url,API),后端根據接口返回相應的數據(json, xml等),圖片可能是(jpg,png等)。這就提高了開發效率,另一方面,由於前后端分離,使得一個后台可以支持多個前台,pc端,移動端,甚至微信小程序(降低了成本)。
網站也叫web App,只不過網站可能更注重內容的顯示,而App在功能處理方面更加強大。如果你還說淘寶,京東這樣能處理大流量的電商平台還只是簡單的網站的話,可能就說不過去了。與傳統的移動端App相比,設計架構(客戶端/服務端)應該都是相同的,MVC模式,模板渲染層,業務邏輯層,數據存儲層。web App每次打開頁面都要將靜態文件加載到瀏覽器端,所以很大程度上具有了高時延的特點,而移動端App是把靜態文件事先下載到手機,然后在打開的時候進行數據的填充渲染,這就使得手機軟件的占用空間很大,很多人從本來在高質量的網絡環境下的打開一個手機瀏覽器就可以沖浪的情況下,還要下載一個幾十甚至上百兆的軟件,這是一個很不爽的事。另外因為網站雖然具有高時延的特點,一些對響應時間要求不大的網頁游戲,其實也可以由網站實現。博主能力有限,表述不合適,請見諒
切回正題。

一、RESTful簡介

RESTful架構,就是目前最流行的一種互聯網軟件架構。它結構清晰、符合標准、易於理解、擴展方便,所以正得到越來越多網站的采用。
REST(英文:Representational State Transfer,簡稱REST)描述了一個架構樣式的網絡系統,比如 web 應用程序。它首次出現在 2000 年 Roy Fielding 的博士論文中,他是 HTTP 規范的主要編寫者之一。值得注意的是REST並沒有一個明確的標准,而更像是一種設計的風格。
R:資源(Resources),REST的名稱"表現層狀態轉化"中,省略了主語。"表現層"其實指的是"資源"(Resources)的"表現層"。所謂"資源",就是網絡上的一個實體,或者說是網絡上的一個具體信息。它可以是一段文本、一張圖片、一首歌曲、一種服務,總之就是一個具體的實在。你可以用一個URI(統一資源定位符)指向它,每種資源對應一個特定的URI。要獲取這個資源,訪問它的URI就可以,因此URI就成了每一個資源的地址或獨一無二的識別符。所謂"上網",就是與互聯網上一系列的"資源"互動,調用它的URI。(面向資源編程)
E:表現層(Representation),"資源"是一種信息實體,它可以有多種外在表現形式。我們把"資源"具體呈現出來的形式,叫做它的"表現層"(Representation)。比如,文本可以用txt格式表現,也可以用HTML格式、XML格式、JSON格式表現,甚至可以采用二進制格式;圖片可以用JPG格式表現,也可以用PNG格式表現。URI只代表資源的實體,不代表它的形式。嚴格地說,有些網址最后的".html"后綴名是不必要的,因為這個后綴名表示格式,屬於"表現層"范疇,而URI應該只代表"資源"的位置。它的具體表現形式,應該HTTP請求的頭信息中用Accept和Content-Type字段指定,這兩個字段才是對"表現層"的描述。(django的接受到客戶端發送的請求request后會對request的請求頭headers做解析,判斷數據的格式content-type)
ST:狀態轉化(State Transfer),訪問一個網站,就代表了客戶端和服務器的一個互動過程。在這個過程中,勢必涉及到數據和狀態的變化。互聯網通信協議HTTP協議,是一個無狀態協議。這意味着,所有的狀態都保存在服務器端。因此,如果客戶端想要操作服務器,必須通過某種手段,讓服務器端發生"狀態轉化"(State Transfer)。而這種轉化是建立在表現層之上的,所以就是"表現層狀態轉化"。
客戶端用到的手段,只能是HTTP協議。具體來說,就是HTTP協議里面,四個表示操作方式的動詞:GET、POST、PUT、DELETE。它們分別對應四種基本操作:GET用來獲取資源,POST用來新建資源(也可以用於更新資源),PUT用來更新資源,DELETE用來刪除資源。
定義:簡單來說REST是一種系統架構設計風格(而非標准),一種分布式系統的應用層解決方案。
目的:Client和Server端進一步解耦。

二、RESTful API設計指南:

1、協議

API與用戶的通信協議,總是使用HTTPs協議。

2、域名

<1>.應該盡量將API部署在專用域名之下,(這中情況會存在跨域問題)

https://api.example.com

<2>.如果確定API很簡單,不會有進一步擴展,可以考慮放在主域名下。

https://example.org/api/

3、版本(Versioning)

應該將API的版本號放入URL。

https://api.example.com/v1/

另一種做法是,將版本號放在HTTP頭信息中,但不如放入URL方便和直觀。

https://api.example.com/?version=v1

4、路徑

路徑又稱"終點"(endpoint),表示API的具體網址,視網絡上任何東西都是資源,均使用名詞表示(可復數),在RESTful架構中,每個網址代表一種資源(resource),所以網址中不能有動詞,只能有名詞,而且所用的名詞往往與數據庫的表格名對應。一般來說,數據庫中的表都是同種記錄的"集合"(collection),所以API中的名詞也應該使用復數

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

5、HTTP動詞

對於資源的具體操作類型,由HTTP動詞表示。

常用的HTTP動詞有下面五個(括號里是對應的SQL命令)。

GET(SELECT):從服務器取出資源(一項或多項)。
POST(CREATE):在服務器新建一個資源。
PUT(UPDATE):在服務器更新資源(客戶端提供改變后的完整資源)。
PATCH(UPDATE):在服務器更新資源(客戶端提供改變的屬性)。
DELETE(DELETE):從服務器刪除資源。

還有兩個不常用的HTTP動詞。

HEAD:獲取資源的元數據。
OPTIONS:獲取信息,關於資源的哪些屬性是客戶端可以改變的。

下面是一些例子。

GET /zoos:列出所有動物園
POST /zoos:新建一個動物園
GET /zoos/ID:獲取某個指定動物園的信息
PUT /zoos/ID:更新某個指定動物園的信息(提供該動物園的全部信息)
PATCH /zoos/ID:更新某個指定動物園的信息(提供該動物園的部分信息)
DELETE /zoos/ID:刪除某個動物園
GET /zoos/ID/animals:列出某個指定動物園的所有動物
DELETE /zoos/ID/animals/ID:刪除某個指定動物園的指定動物

6、過濾信息(Filtering)

如果記錄數量很多,服務器不可能都將它們返回給用戶。API應該提供參數,過濾返回結果。

下面是一些常見的參數。

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:指定篩選條件

參數的設計允許存在冗余,即允許API路徑和URL參數偶爾有重復。比如,GET /zoo/ID/animals 與 GET /animals?zoo_id=ID 的含義是相同的。

7、狀態碼(Status Codes)

服務器向用戶返回的狀態碼和提示信息,常見的有以下一些(方括號中是該狀態碼對應的HTTP動詞)。

200 OK - [GET]:服務器成功返回用戶請求的數據,該操作是冪等的(Idempotent)。
201 CREATED - [POST/PUT/PATCH]:用戶新建或修改數據成功。
202 Accepted - [*]:表示一個請求已經進入后台排隊(異步任務)
204 NO CONTENT - [DELETE]:用戶刪除數據成功。
400 INVALID REQUEST - [POST/PUT/PATCH]:用戶發出的請求有錯誤,服務器沒有進行新建或修改數據的操作,該操作是冪等的。
401 Unauthorized - [*]:表示用戶沒有權限(令牌、用戶名、密碼錯誤)。
403 Forbidden - [*] 表示用戶得到授權(與401錯誤相對),但是訪問是被禁止的。
404 NOT FOUND - [*]:用戶發出的請求針對的是不存在的記錄,服務器沒有進行操作,該操作是冪等的。
406 Not Acceptable - [GET]:用戶請求的格式不可得(比如用戶請求JSON格式,但是只有XML格式)。
410 Gone -[GET]:用戶請求的資源被永久刪除,且不會再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 當創建一個對象時,發生一個驗證錯誤。
500 INTERNAL SERVER ERROR - [*]:服務器發生錯誤,用戶將無法判斷發出的請求是否成功。

8、錯誤處理(Error handling)

如果狀態碼是4xx,就應該向用戶返回出錯信息。一般來說,返回的信息中將error作為鍵名,出錯信息作為鍵值即可。

{
    error: "Invalid API key"
}

9、返回結果

針對不同操作,服務器向用戶返回的結果應該符合以下規范。

GET /collection:返回資源對象的列表(數組)
GET /collection/resource:返回單個資源對象
POST /collection:返回新生成的資源對象
PUT /collection/resource:返回完整的資源對象
PATCH /collection/resource:返回完整的資源對象
DELETE /collection/resource:返回一個空文檔

10、Hypermedia API

RESTful API最好做到Hypermedia,即返回結果中提供鏈接,連向其他API方法,使得用戶不查文檔,也知道下一步應該做什么。

比如,當用戶向api.example.com的根目錄發出請求,會得到這樣一個文檔。

{"link": {
  "rel":   "collection https://www.example.com/zoos",
  "href":  "https://api.example.com/zoos",
  "title": "List of zoos",
  "type":  "application/vnd.yourformat+json"
}}

上面代碼表示,文檔中有一個link屬性,用戶讀取這個屬性就知道下一步該調用什么API了。rel表示這個API與當前網址的關系(collection關系,並給出該collection的網址),href表示API的路徑,title表示API的標題,type表示返回類型。

摘自ruanyifeng博客

三、django rest famework


免責聲明!

本站轉載的文章為個人學習借鑒使用,本站對版權不負任何法律責任。如果侵犯了您的隱私權益,請聯系本站郵箱yoyou2525@163.com刪除。



 
粵ICP備18138465號   © 2018-2025 CODEPRJ.COM