使用 Postman 串接 API
在開始撰寫 Swift 程式串接後台的 API 前,最好先利用一些工具確認後台功能是否正常,以及檢查對方回傳的 JSON 資料格式。如果發現後台有 bug,我們 App 工程師就可以先去買個下午茶休息一下了。
能夠幫忙我們串接 API 的工具很多,若要選一個武林盟主,Postman App 應該是目前最受歡迎,最多人採用的工具。Postman 人如其名,是世界上除了老闆以外,最會發送 Request 的超人 ~
連到 Postman 網站
從 Sign Up for Free 註冊帳號
進入串接 API 的工作空間(workspace)
登入後我們可以進入串接 API 的工作空間,從 PostMan 的網站直接測試 API。
我們可透過以下兩個方法進入串接 API 的工作空間。
- 方法1: 還沒有工作空間時必須先建立工作空間
點選 Send a request。
此時 PostMan 會自動幫我們建立並進入工作空間 My Workspace。
- 方法 2: 點選之前建過的工作空間。
Recently visited workspaces 將顯示之前建立的工作空間,在此我們點選 My Workspace。
串接 API,發送 request
進入工作空間後,點選右上的 +,新增我們想測試的 API。
從剛剛新增的 Untitled Request 頁面測試 API。
從下圖的下拉選單可選擇 GET,POST,DELETE 等常見的 HTTP method,接下來我們將透過 GET API 抓取 iTunes 的音樂資料,因此我們選擇 GET。
在 GET 右邊的框框輸入 API 的網址,比方輸入以下字串搜尋戴佩妮的金曲怎樣。
https://itunes.apple.com/search?term=怎樣&media=music
點選 Send 發送。
如果想要下載 JSON 檔,可點選 Send 旁的箭頭,然後選擇 Send and Download。
檢視 API 回傳的結果
從下方的 Body 區塊可看到 API 回傳的結果。
由於我們發送的 iTunes API 將回傳 JSON,因此我們可將顯示的格式改成 Pretty 的 JSON,以美美的彩色格式顯示。
如下圖所示,現在我們很容易就能從 JSON 裡找到 penny 歌曲怎樣的相關資料。
我們也可以點選下圖右上角的正方形按鈕複製 JSON 內容。
進階的 API 欄位設定
除了設定 API 的網址 & HTTP method,我們還可以設定它的 Params,Authorization,Headers,Body 等欄位,因此基本上再複雜的 API 都難不倒 Postman。
比方我們可以設定以下資訊。
- 從 Authorization 設定 API Key。
- 從 Headers 設定 HTTP header。
- 切換到 Body 的 raw 分頁,設定上傳的 JSON 資料。
除了貼上 JSON 資料,記得要點選右邊的箭頭,將資料格式設為 JSON。
- 切換到 Body 的 form-data 分頁,從 Body 設定上傳的檔案。
輸入欄位(KEY)名稱,比方 image,然後從 KEY 的下拉選單選擇 File。
點選 Select Files。
import curl 指令
許多第三方 API 的網站都在官方文件裡以 curl 指令說明 API,比方以下 SheetDB get all data API 的 curl 指令為
curl https://sheetdb.io/api/v1/58f61be4dda40?sort_by=name&sort_order=asc
Postman 貼心地提供了 import curl 指令的功能,因此我們可以直接將 curl 指令加入 Postman 測試,步驟如下:
- 點選下圖紅色框框的 Import。
- 切換到 Raw Text 分頁。
- 貼上 curl 指令後點選 Continue。
特別要注意的,curl 指令裡的網址要加上單引號,否則會有問題。
點選 Import。
成功 import 後,Postman 將自動幫我們產生 API 的 Request。
點選 Send 即可測試它回傳的 JSON 資料。
查看 JSON 的樹狀圖和資料型別
若想更清楚地查看 JSON 的樹狀圖和資料型別,可參考以下連結。
其它使用 PostMan 的方法: 下載 Postman App
除了從 PostMan 的網站測試 API,我們也可以下載 Postman 的 Mac App,從 App 測試 API。
產生 API 的程式碼
比起網頁版的 PostMan,使用 Mac 版的 PostMan 有個特別功能,它可以幫我們產生 API 的程式碼,方法如下:
- 點選 Save 下方的 Code。
此時將出現 generate code snippets 的視窗,包含 curl,Swift 和各種程式語言的版本。
- 選擇 Swift — URLSession。
從下圖的右半部我們可看到 Postman 幫我們產生的 Swift 程式,點選右上角的正方形按鈕即可複製。
比方我們將剛剛的程式貼到 Xcode 的 playground,即可看到它完美無暇地抓到 JSON 資料。