API 串接實戰：看懂文件、Postman 測試、requests 補強

API 文件是 AI 的原始資料，你把正確的文件資訊給 AI，它就能生出正確的串接程式；給錯了，生出來的也是錯的。這一課教你三個步驟：先看懂文件的五個區塊，再用 Postman 測通，最後讓 AI 把測試結果補強成完整、有錯誤處理的 Python 程式。

學會複用這套流程之後，換一個 API 也只是換 URL 和參數，不用每次都從零開始問 AI。

看懂 API 文件：必讀的五個區塊

用 Postman 先測試，再讓 AI 寫程式

Postman 是一個 API 測試工具，讓你在寫程式之前先確認 API 可以打通。

1. 下載並開啟 Postman，建立新的 Request。
2. 選擇方法，GET 或 POST，輸入 API 的完整 URL。
3. 在 Headers 頁籤加入 Authorization 和 Content-Type。
4. 如果是 POST，在 Body 選 raw、JSON，填入要傳的資料。
5. 點 Send，確認狀態碼是 200，且 Response 格式符合預期。
6. 測試成功後，點 Code 再選 Python Requests，Postman 會自動生成 Python 程式碼。

requests 完整用法

import requests, os
from dotenv import load_dotenv

load_dotenv()

headers = {
    "Authorization": f"Bearer {os.getenv('API_KEY')}",
    "Content-Type": "application/json",
}
payload = {"query": "weather taipei", "lang": "zh"}

try:
    r = requests.post("https://api.example.com/search",
        headers=headers, json=payload, timeout=10)
    r.raise_for_status()  # 4xx or 5xx 自動拋出 exception
    data = r.json()
except requests.exceptions.Timeout:
    print("request timed out")
except requests.exceptions.HTTPError as e:
    print(f"http error: {e.response.status_code}")

處理 API 回傳：成功、失敗、分頁

拿到 Response 之後，先判斷狀態碼再安全取值，不要假設欄位一定存在。

if r.status_code == 200:
    data = r.json()
    items = data.get("items", [])   # 安全取值，沒有給空 list
    total = data.get("total", 0)
    print(f"total {total}, got {len(items)}")
else:
    error = r.json().get("error", "unknown error")
    print(f"error {r.status_code}: {error}")

資料量大的 API 通常會分頁，要全部取完得用迴圈，直到回傳結果顯示沒有下一頁為止。

all_items = []
page = 1
while True:
    r = requests.get(url, params={"page": page, "per_page": 100}, headers=headers)
    data = r.json()
    all_items.extend(data.get("items", []))
    if not data.get("has_next", False):
        break
    page += 1

AI 串接 API 的四個常見問題