一、web API接口
什么是web API接口？：
明確了請求方式，提供對應后台所需參數，請求url鏈接可以得到后台的響應數據
url : 返回數據的url
https://api.map.baidu.com/place/search
請求方式：
get，post,put,patch....
請求參數：json或xml格式的key-value類型數據
- ak：6E823f587c95f0148c19993539b99295
- region：上海
- query：肯德基
- output：json
響應結果：
返回json或xml格式的key-value類型數據
-
上方請求參數的output參數值決定了響應數據的格式
-
{ "status":0, "message":"ok", "results":[ { "name":"肯德基(羅餐廳)", "location":{ "lat":31.415354, "lng":121.357339 }, "address":"月羅路2380號", "province":"上海市", "city":"上海市", "area":"寶山區", "street_id":"339ed41ae1d6dc320a5cb37c", "telephone":"(021)56761006", "detail":1, "uid":"339ed41ae1d6dc320a5cb37c" } ... ] }
怎么寫接口？：
參照某種規則（規范）書寫url鏈接，同時根據規則制定請求方式，請求數據與響應結果
接口文檔：
提供給前后台開發人員與測試人員查看
接口工具：
YAPI平台
專門寫接口文檔的YAPI平台 http://yapi.demo.qunar.com/
YApi是去哪兒網的前端技術中心的一個開源可視化接口管理平台。
- 創建接口項目
- 創建接口
- 編寫接口
接口測試工具：Postman
Postman是一款接口調試工具，是一款免費的可視化軟件，同時支持各種操作系統平台，是測試接口的首選工具。
Postman可以直接從官網：https://www.getpostman.com/downloads/下載獲得，然后進行傻瓜式安裝。
- 工作面板
- 簡易的get請求
- 簡易的post請求
- 案例：請求百度地圖接口
接口規范：
webapi接口規范：restful
RESTful API介紹
RESTful介紹
REST與技術無關，代表的是一種軟件架構風格，REST是Representational State Transfer的簡稱，中文翻譯為“表征狀態轉移”或“表現層狀態轉化”。
推薦閱讀 阮一峰 理解RESTful架構
RESTful API設計指南
推薦閱讀 阮一峰 RESTful設計指南
API與用戶的通信協議
總是使用HTTPs協議。
域名
用api關鍵字來標識接口url
注：看到api字眼，就代表該請求url鏈接是完成前后台數據交互的
版本
\1. 將版本信息放在URL中，如：
v1，v2代表不同數據版本的提現，前提是一種數據資源有多個版本
\2. 將版本信息放在請求頭中。
url路徑
視網絡上任何東西都是資源，均使用名詞表示（一般為復數形式）
https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees
在url鏈接中獎勵不要出現操作資源的動詞
錯誤示范：https://api.baidu.com/delete-user
特殊的接口可以出現動詞，因為這些接口一般沒有一個明確的資源，或是動詞就是接口的核心含義
method請求方式
GET ：從服務器取出資源（一項或多項）
POST ：在服務器新建一個資源
PUT ：在服務器更新資源（客戶端提供改變后的完整資源）
PATCH ：在服務器更新資源（客戶端提供改變的屬性）
DELETE ：從服務器刪除資源
過濾
通過在url上傳參的形式傳遞搜索條件
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：指定篩選條件
狀態碼
200 OK - [GET]：服務器成功返回用戶請求的數據，該操作是冪等的（Idempotent）。
201 CREATED - [POST/PUT/PATCH]：用戶新建或修改數據成功。
202 Accepted - [*]：表示一個請求已經進入后台排隊（異步任務）
204 NO CONTENT - [DELETE]：用戶刪除數據成功。
301：永久重定向
302：暫時重定向
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 - [*]：服務器發生錯誤，用戶將無法判斷發出的請求是否成功。
錯誤處理
狀態碼是4xx時，應返回錯誤信息，error當做key。
{
error: "Invalid API key"
}
返回結果
針對不同操作，服務器向用戶返回的結果應該符合以下規范
GET /collection：返回資源對象的列表（數組）
GET /collection/resource：返回單個資源對象
POST /collection：返回新生成的資源對象
PUT /collection/resource：返回完整的資源對象
PATCH /collection/resource：返回完整的資源對象
DELETE /collection/resource：返回一個空文檔
{
"status": 0,
"msg": "ok",
"results":[
{
"name":"肯德基(羅餐廳)",
"location":{
"lat":31.415354,
"lng":121.357339
},
"address":"月羅路2380號",
"province":"上海市",
"city":"上海市",
"area":"寶山區",
"street_id":"339ed41ae1d6dc320a5cb37c",
"telephone":"(021)56761006",
"detail":1,
"uid":"339ed41ae1d6dc320a5cb37c"
}
...
]
}
Hypermedia API
RESTful API最好做到Hypermedia，即返回結果中提供鏈接，連向其他API方法，使得用戶不查文檔，也知道下一步應該做什么。
{"link": {
"rel": "collection https://www.example.com/zoos",
"href": "https://api.example.com/zoos",
"title": "List of zoos",
"type": "application/vnd.yourformat+json"
}}