restful介面規範

  什麼是介面規範?介面規範就是為了採用不同的後臺語言,也能使用同樣的介面獲取到同樣的資料。如何寫介面:介面規範是規範化書寫介面的,寫介面要寫url、響應資料

​  注:如果將請求引數也納入考量範圍,那就是在寫介面文件

url

restful介面的url規範,遵循以下6個規範

1.用關鍵字標識介面url

比如登入的介面,可以用下面的url,這樣我們閱讀的時候,一眼就能看出這個是登入介面

www.baidu.com/login/

2.介面資料安全性決定優先選擇https協議

3.如果一個介面有多版本存在,需要在url中標識體現

假如我們剛開發一個後臺,那第一個版本就是v1

api.baidu.com/v1/

後面介面需要升級,那麼就將介面升級為v2

api.baidu.com/v2/

4.介面操作的資料來源稱之為資源,在url中一般採用資源複數形式,一個介面可以概括對該資源的多種操作方式

獲取全部書籍

api.baidu.com/books

獲取指定的書籍

api.baidu.com/books/(pk)

5.請求方式有很多種,用一個url處理如何保證不混亂 - 通過請求方式標識操作資源的方式

獲取所有書籍,使用get請求

/books/

增加一本書籍,使用post請求

/books/

刪除一本書籍,使用delete請求

/books/(pk)

整體更新一本書籍的內容,使用put請求

/books/(pk)

區域性更新一本書籍的一個欄位,使用patch請求

/books/(pk)

6.資源往往涉及資料的各種操作方式 - 篩選、排序、限制

api.baidu.com/books/?search=jkc&ordering=price&limit=3

響應資料

響應資料遵循以下4個規範

1.http請求的響應會有響應狀態碼,介面用來返回操作的資源資料,可以擁有操作資料結果的狀態碼

status    0(操作資源成功)    1(操作資源失敗)    2(操作資源成功,但沒匹配結果)

注:資源狀態碼不像http狀態碼,一般是後臺與前臺或者是客戶約定的

2. 資源的狀態碼文字提示

status    ok    '賬號有誤'    '密碼有誤'    '使用者鎖定'

3. 資源本身

data: {
業務資料
}

4. 不能直接返回的資源(子資源、圖片、視訊等資源),返回該資源的url連結