API測試工具 Postman 新手教學|使用Postman 開發出你的第一支 API

大家都說 Postman 是測試 API 必備神器,必備到就像 WiFi 跟你一樣的關係,沒有他會覺得斷手斷腳,跟個廢人一樣。只是對於新手一來說,一打開好多按鈕,好多專有名詞,真的是深深體會到自己多菜,不怕!,服用本篇新手教學,幫你入門,開電扇趕走菜味.

本篇是給 Postman 新手入門使用,讓你在 10 分鐘快速上手基本 Postman 用法,從基本 GET API ,到需要驗證的 POST API,其中會一起補充一些基本觀念,包含請求四大方法(Create/Read/Update/Delete),Header 參數簡介,最後 Bonus,使用 Postman 上傳/下載檔案.貼心讓你不用一直點分頁去 Google。


安裝 Postman

請你到 Postman 的官方網站下載應用程式:https://www.getpostman.com/downloads/

安裝好之後打開軟體,會看到以下的操作介面:

postman 操作介面

Postman 導覽:主要操作版面

一開始使用,我們只需要專注在版面右側的 Request 頁籤版面,你可以透過兩個方式看到Request 頁籤

  1. 左上角的 [+New] 跳出的選單,新增一個新的 Request 頁籤
  2. 直接在點選現有 Request 頁籤 旁的 [+] 新增,就像平常新增 google 分頁一樣

Request 頁籤,可以大略分成三個區塊,分別是 網址區塊,參數區塊,回應區塊,每個區塊需要關注哪些部分,又各自代表什麼意義,可以參考各區塊的解說

  • 網址區塊,選擇 API 的方法、請求路徑 URL
  • 參數區塊,詳細設定 API 三大部分參數( 網址 / Header / Body)
  • 回應區塊,檢視 API 回應的資料、回應的資訊

第一部分:網址區塊介紹

區塊簡介

為了方便理解,你可以先把接收 API 的 Server  當作是替你服務的小助理,負責代替你做各種任務,在這裡個區塊,你需要設定請求方法、請求網址,完成後,點選右側 [Send] 送出

Method 請求方法 | 小助理替你服務的類型,常見有四個

  • GET,取得 (GET) 資料
  • POST,新增 (Create) 資料
  • PUT,更新 (Update) 資料
  • DELETE,刪除 (Delete) 資料

URL 請求網址 | 小助理要到哪裡執行你交辦的任務


第二部分:參數區介紹

區塊簡介

我們會在請求三個地方,附加特定資訊,提供請求的細部設定,分別是 URL 網址、Header、Body

  • URL 網址,通常關於取得資料的篩選,都會放在這裡,可以加上兩種參數,Query Params 搜尋參數,Path Variables 路徑變數,搭配使用,做資料的篩選整理,特別注意不可以把密碼等敏感資訊放在網址
  • Header 部分,通常關於 API 請求的標示,都會存放在這裡,例如需要身份驗證的請求,會把驗證身份的token 以 Key-Value 存在 Header (ex. Authorization: token)
  • Body 部分,通常 API 需要提交給 Server 的資料,都會放在這裡(ex.註冊表單 name: 小明, password:1234)

Params 網址參數頁 | (設定 Query Params 搜尋參數 Path Variables 路徑變數 )

  • 預設只有  Query Params 搜尋參數,Path Variable 路徑變數,需要自行在網址上打上冒號+變數名 (ex.  ” : name ” ),才會出現
  • 設定方式都是採 Key – value ,可以根據情況彈性勾選

Authorization 驗證設定頁 |用來設定 Header 中的 Authorization 參數

常用驗證類型

  • No Auth | 不需要驗證
  • Basic Auth |帳號,密碼型驗證
  • token 驗證 |token 型驗證

Header 頁|用來設定 Header 中的其他參數

Postman 把一些必要參數隱藏起來,如果需要特別設定,可以取消隱藏,進行修改

另外 Authorization 雖然沒有在這裡出現,不過 Authorization 驗證設定頁若有指定,還是會一起送出請求

常見參數

  • User-Agent | 告知 Server,發出 Request 的 Client 瀏覽器、作業系統等資訊 |doc
  • Accept |告知 Server,Client 可以解讀的內容類型 | doc
  • Content-type | 告知 Server,Client 提交什麼類型內容 |doc

Body 頁

比較常用的是 form-data 、x-www-form-urlencoded、raw,前兩者都是送出表單資料,最後一個提供較多彈性的資料格式,目前大部分都是使用 Json 只需要選擇 x-www-form-urlencoded 就可以了

  • form-data vs. x-www-form-urlencoded 有什麼不一樣呢?

  • form-data 不會針對內容,進行編碼,x-www-form-urlencoded  會以 Key1 = val1 進行編碼
  • 需要上傳檔案,用 form-data,選擇 file 類型,一般的表單資料用 x-www-form-urlencoded

postman json 資料要放哪裡?

選擇 raw 選項,並且在右側下拉選單,選擇 JSON 格式


第三部分:回應區介紹

區塊簡介

  • 成功接收到回應後,下方回應區塊就會有內容提供你參考,Postman 很貼心幫忙把回應資料分門別類,大部分情況只會檢視 Body 資料,如果有特別的需求,可以檢視 Cookie 和 Header ,是否有被加東西,另外開發時會特別關注版面右上的 回應資訊,例如狀態碼、回應時間、回應大小

回應資訊欄

Status code 狀態碼 |表示 API 回應狀況,常見如下

  • 200 | 成功取得回應
  • 400 | 請求參數錯誤 (檢查輸入的參數,是否符合 API 規定)
  • 401 | 未認證 (未登入認證,但請求需要登入的 API)
  • 404 | 請求的資源不存在 (新手常見是,URL 打錯,再檢查看看吧)
  • 500 | 內部 Server 出錯 (不關你的事,可能是 Server 掛掉了)

Time 回應時間 |注重效能會特別查看這一塊,單位是 ms 微秒

架設 web API 伺服器或串接後端 API,3 分鐘小測驗取得學習建議


Q&A 問答時間

Q:Postman 可以處理需要,上傳檔案的 API 嗎?(ex.  Postman upload  image.jpg )

A:可以的,設定步驟如下

  1. 確認你的提交方法為 POST
  2. 在 Body 分頁,選擇 form-data 格式,選擇 Key 類型是 file,填入 Key 名稱,點選 “Select Files” 上傳檔案
  3. 在 Header 分頁,KEY 欄位 Content-Type ,Value 欄位更改為 multipart/form-data ;(當你在成功上傳檔案,Postman 會自動幫你,完成步驟 3 )

Q:乘上,那下載檔案的 API 呢?(ex. Postman download user.csv )

A:答|可以的,設定步驟如下

  • 完成所有 API 設定後,提交按鈕,選擇下拉箭頭,點選“send and Download”(這個選項,如果 api 返回需要下載的檔案,會自動幫你下載儲存)

以上就是給新手的 Postman 基本操作使用介紹,如果想要有更深入的瞭解和操作,歡迎參考 ALPHA Camp 的課程 全端工程師養成:實戰學習架設 Web API 伺服器

(本文作者是 ALPHA Camp 的助教,後端工程師 Water