1.2 閱讀 API 文件
本節要點
- 如何閱讀API文件
- API文件實例講解
課前準備
API測試工具
提前準備一個API測試工具，以下工具任選其一：
- POSTMAN （可選）
POSTMAN是最好用的API測試工具！
點擊此連結Postman | Download Postman App進入Postman官網下載頁面，選擇相應的版本（操作系統 及 32位/64位）並安裝；
正常的話，瀏覽器會自動辨識處你的電腦系統，本教學用macOS電腦打開的，圖中圈出的地方會自動辨識電腦系統；
Windows使用者需要選擇32位或是64位版本，你需要先查看你所使用的電腦是32位還是64位處理器，如果你不清楚，可以在電腦設定中查看；
點擊下載，直接打開壓縮包安裝即可。
安裝後打開軟體需要註冊，分別填寫信箱、使用者名、密碼，下兩個框均需要勾選，然後點擊橙色按鈕，註冊一個免費帳戶。
- POSTWOMAN （可選）
是一個用於替代Postman,免費開源、輕量級、快速且美觀的API偵錯工具。能幫助程式員節省時間,提升工作效率；
無需下載，造訪官網即可使用！
點擊造訪：POSTWOMAN官網
- Apizza（可選）
極客專屬的API協作管理工具；
點擊造訪：Apizza官網
- ApiPost（可選）
ApiPost是一個支援團隊協作，並可直接生成文件的API偵錯、管理工具，支援模擬POST、GET、PUT等常見請求，是後台API開發者或前端、API測試人員不可多得的工具；
點擊造訪：ApiPost官網
API準備
課程內容
如何看API文件？
API文件一般分為API描述、API地址、請求方法、請求參數、回應內容、錯誤程式碼、實例幾個部分：
API描述：簡單描述API的邏輯和作用。例如說明這是一個發送訊息的API、查詢天氣的API；
API地址：這個地址表示的是網絡地址，即url，我們需要調用APIurl，取得回應內容；
請求方法：常見的請求方法為GET和POST，其他的方式見下圖；
請求參數：用來傳遞資訊的變數。即需要請求的欄位名的名稱和規則：都是哪些欄位，欄位的類型是什麼，是否必填欄位等等；
- URL傳參
- Headers 請求頭
- Body 請求內容
回應內容：API返回的欄位名稱和規則；
錯誤程式碼：對API的錯誤用程式碼進行歸類，以便能快速找到錯誤原因，解決問題；
實例：實際調用時的回應的內容。
這裡需重點掌握 GET 和 POST 請求方式！
GET請求
GET通常用於取得服務端資料：
- GET方式在url後面拼接參數，只能以文字的形式傳遞參數；
- 傳遞的資料量小，4kb左右（不同瀏覽器會有差異）；
- 安全性低，會將資訊顯示在地址欄；
- 速度快，通常用於對安全性要求不高的請求；
- GET請求也可以有Headers參數
URL解析：
- 請求域名（Host）：https://zhidao.baidu.com
- 請求路徑：/search
(有的文件需要自己域名+路徑，也有的文件會提供完整的API地址，例如Jodoo)
- ？ 代表開始傳參
- & 代表下一個參數
- 請求參數：
參數名 | 值 |
lm | 0 |
rn | 10 |
pn | 0 |
fr | search |
ie | gbk |
word | %BC%F2%B5%C0%D4%C6 |
在GET請求中，遇到 參數 / Params / Querys 均是以 URL傳參的形式進行傳遞！
附註：
在POSTMAN中，可以直接用 URL傳參形式，也可以在Params處填寫KEY和VALUE，會自動進行拼接（演示）！
POST請求
- post送出資料相對於get的安全性高一些。（注意：抓包軟體也會抓到post的內容，安全性要求高可以進行加密）；
- 傳遞資料量大，請求對資料長度沒有要求；
- 用於密碼等安全性要求高的場合，送出資料量較大的場合，如上傳文件，發佈文章等。
POST請求一般由Url 、 Headers 、 Body組成，如果在POST請求的API文件裏遇到 Params / Querys 則需以像GET請求一樣使用URL參數傳遞參數，而POST請求的API文件裏面的參數一般指Body！
POST請求不同的請求格式：
- application/json，JSON資料格式，一般使用raw-JSON，最常見的格式，我們後期調用API和自己開發API，均是以JSON為主；
- 如下所示，參數1的key：name，參數1的value：ziv，參數2的key：password，參數2的value：123
{"name":"ziv","password":"123"}- 如下所示，參數1的key：data_id，參數1的value：5398d19a9318483922
{"data_id":"5398d19a9318483922"}- text/xml（瞭解），XML資料格式，一般使用raw-XML；
<?xml version="1.0" encoding="UTF-8" ?>
<name>ziv</name>
<password>123</password>- multipart/form-data（瞭解），它會將表單的資料處理為一條訊息，以標籤為單元，用分隔符號分開。由於有boundary隔離，所以multipart/form-data既可以上傳文件，也可以上傳鍵值對，它採用了鍵值對的方式，所以可以上傳多個文件；
- application/x-www-from-urlencoded（瞭解），會將表單內的資料轉換為鍵值對，&分隔。API地址