接口規范

一、Web API接口

1.1 什么是接口

​ 同通過網絡，規定前后台信息交互規則的url連接，是前后台信息交互的媒介。

1.2 接口的組成

​ 1、url;

​ 2、請求方式：get、post、put、patch、delete;

​ 3、請求參數：json或xml格式的key-value類型數據；

​ 4、響應結果：json或者xml格式的數據

1.3 編寫接口文檔

​ 編寫接口文檔可以使用去哪網技術中心的一個開源可視化接口管理平台YApi。

​ http://yapi.demo.qunar.com/

​

二、Restful接口規范

​ REST全稱是Representational State Transfer，中文意思是表述性狀態轉移,首次出現是在2000年Roy Fielding的博士論文中。

2.1 URL設計

​ 1、數據安全的保障

​ url連接一般采用https協議進行數據傳輸，可以提高數據交互過程中的安全性。

​ 2、接口特征的表現

​ 使用api關鍵字標識接口：https://api.lalala.com。

​ 注意：出現api，就代表該請求的url連接是為了完成前后台數據交互的。

​ 3、多版本數據共存

​ https://api.lalala.com/v1與https://api.lalala.com/v2，就是不同版本數據的體現。

​ 4、數據即資源

​ 接口即前后端交互的媒介，交互的數據即為資源。

​ https://api.lalala.com/users、https://api.lalala.com/data。

​ 推薦資源寫復數形式，便於理解。

​ 連接中不要出現操作資源的動詞，例如https://api.lalala.com/delete-user。

​ 沒有明確資源的接口可以使用動詞，或者東西就是接口的核心含義可以使用動詞。

​ 例：https://api.lalala.com/login或https://api.lalala.com/content/search

2.2 響應狀態碼

1、正常響應

• 響應狀態碼2xx

  • 200：常規請求
  • 201：創建成功

  2、重定向響應

• 響應狀態碼3xx

  • 301：永久重定向
  • 302：暫時重定向

  3、客戶端異常

• 響應狀態碼4xx

  • 403：請求無權限
  • 404：請求路徑不存在
  • 405：請求方法不存在

  4、服務器異常

• 響應狀態碼5xx

  • 500：服務器異常