Skip to content

Data Science › Python Foundations › API 與 HTTP

API 與 HTTP (Web APIs with requests) ​

呼叫 Web API 的流程很固定:組 URL → 加查詢參數、標頭、認證 → 送出請求 → 檢查狀態碼 → 解析回應 → 明確處理錯誤。Python 的預設工具是 requests;生資常見的 Ensembl REST、NCBI E-utilities、UniProt 都是這個模式。自己寫 API(伺服器端)見 FastAPI,瀏覽器與 HTTP 的整體運作見 Web 基礎。

HTTP 請求與回應 ​

text
Request                                   Response
  method   GET / POST / PUT / DELETE        status   200 / 404 / 429 / 500
  URL      https://api.x.org/genes/42       headers  Content-Type: application/json
           └ base ┘└ path ┘?q=TP53          body     {"id": 42, ...}
  headers  Accept, Authorization
  body     JSON(POST / PUT 時)
方法用途冪等 (idempotent)?
GET取得資源(最常用)是
POST建立資源;也常用於參數太長的查詢否
PUT整筆取代是
PATCH部分更新不一定
DELETE刪除是

URL 的 path 指向資源(/albums/42/tracks),query string 放篩選、排序、分頁、搜尋條件。

基本請求 ​

python
import requests

r = requests.get(
    "https://rest.ensembl.org/lookup/symbol/homo_sapiens/TP53",
    headers={"Accept": "application/json"},   # 內容協商:要求 JSON
    timeout=10,                               # 一定要設:預設會無限等待
)
r.status_code                  # 200
r.url                          # 實際送出的 URL(含編碼後的參數)
r.headers["Content-Type"]      # 'application/json'
r.json()["id"]                 # 'ENSG00000141510':解析 JSON → dict
r.text                         # 原始字串;r.content 為 bytes(下載檔案用)

# 查詢參數用 params=,自動處理編碼(空白、&、中文)
r = requests.get(
    "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi",
    params={"db": "pubmed", "term": "CRISPR AND 2024[pdat]", "retmode": "json", "retmax": 20},
    timeout=10,
)
r.json()["esearchresult"]["idlist"]

# 送 JSON:用 json=,自動序列化並設 Content-Type: application/json
r = requests.post("https://api.example.com/playlists", json={"name": "Road Trip", "tracks": [1, 2]}, timeout=10)
r.request.headers["Content-Type"]   # 'application/json'
# data= 則是送表單 (application/x-www-form-urlencoded)
回應屬性內容
status_code數字狀態碼
okstatus_code < 400
headers回應標頭(不分大小寫的 dict)
json()解析 JSON;回應不是 JSON 時丟 JSONDecodeError
text / content字串 / bytes
elapsed花費時間

urllib.request 是標準庫的替代品,不想多裝套件時可用,但寫法較囉嗦;非同步大量請求可用 httpx(API 幾乎與 requests 相同,另支援 async 與 HTTP/2)。

狀態碼 ​

類別代表常見該怎麼做
2xx成功200 OK、201 Created、204 No Content—
3xx重新導向301、302、304 Not Modifiedrequests 預設自動跟隨
4xx請求有問題400 參數錯、401 未認證、403 無權限、404 不存在修正請求,重試沒用
429 Too Many Requests降速,依 Retry-After 等待後重試
5xx伺服器有問題500、502 Bad Gateway、503、504 Gateway Timeout稍後重試(指數退避)

錯誤處理 ​

python
import requests

try:
    r = requests.get(url, params=params, timeout=10)
    r.raise_for_status()                        # 4xx / 5xx → HTTPError
    data = r.json()
except requests.HTTPError as e:
    log.error("HTTP %s for %s: %s", e.response.status_code, e.response.url, e.response.text[:200])
    raise
except (requests.ConnectionError, requests.Timeout) as e:
    log.error("network problem: %s", e)
    raise
except requests.JSONDecodeError:
    log.error("not JSON: %s", r.text[:200])     # 常見:錯誤頁回傳的是 HTML
    raise

raise_for_status() 讓成功路徑保持簡單、失敗一定浮現;不要只檢查 if r.status_code == 200 然後默默略過失敗。

Session、重試與限速 ​

大量呼叫時用 Session:重用 TCP 連線(更快),並統一設定標頭與重試。

python
import time
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

session = requests.Session()
session.headers.update({"Accept": "application/json", "User-Agent": "mylab-pipeline/0.1 (me@uni.edu)"})
retry = Retry(
    total=5,
    backoff_factor=1,                           # 等待 1, 2, 4, 8... 秒(指數退避)
    status_forcelist=[429, 500, 502, 503, 504],
    allowed_methods=["GET", "POST"],
    respect_retry_after_header=True,
)
session.mount("https://", HTTPAdapter(max_retries=retry))

for gene in genes:
    r = session.get(f"https://rest.ensembl.org/lookup/symbol/homo_sapiens/{gene}", timeout=10)
    if r.status_code == 404:
        continue                                # 查無此基因:記錄後跳過
    r.raise_for_status()
    results.append(r.json())
    time.sleep(0.1)                             # 遵守服務的速率限制
服務速率限制(以官方文件為準)批次端點
NCBI E-utilities無 API key 每秒 3 次;有 key 每秒 10 次epost + efetch、一次傳多個 ID
Ensembl REST每秒約 15 次POST /lookup/symbol 一次查多個

能批次就批次:一次 POST 1000 個 ID,比 1000 次 GET 快得多也不容易被封鎖。重複執行的分析把回應快取到本地(requests-cache 或自己存 JSON),也能讓結果可重現——線上資料庫會更新。

分頁 (Pagination) ​

python
def fetch_all(url, params, page_size=100):
    """依 offset 分頁抓到沒有資料為止。"""
    offset = 0
    while True:
        r = session.get(url, params={**params, "limit": page_size, "offset": offset}, timeout=10)
        r.raise_for_status()
        items = r.json()["results"]
        if not items:
            break
        yield from items
        offset += page_size

# 另一種常見做法:回應帶下一頁連結
url = "https://rest.uniprot.org/uniprotkb/search?query=gene:TP53&format=json&size=500"
while url:
    r = session.get(url, timeout=30)
    r.raise_for_status()
    handle(r.json()["results"])
    url = r.links.get("next", {}).get("url")    # 解析 Link 標頭
分頁方式參數注意
offset / limitoffset=200&limit=100資料在分頁期間變動時可能重複或遺漏
page numberpage=3&per_page=100同上
cursor / tokencursor=abc... 或 Link: <...>; rel="next"最穩定,大型 API 常用

認證 (Authentication) ​

方式寫法備註
API key(查詢參數)params={"api_key": KEY}NCBI 用這種;URL 可能被記錄在 log
API key(標頭)headers={"X-API-Key": KEY}
Bearer tokenheaders={"Authorization": f"Bearer {TOKEN}"}最常見的現代做法(OAuth 2)
Basic authauth=("user", "password")requests 自動產生 Authorization 標頭;只能走 HTTPS
python
import os
TOKEN = os.environ["MY_API_TOKEN"]          # 從環境變數或 .env 讀,不要寫死在程式或 notebook 裡
session.headers["Authorization"] = f"Bearer {TOKEN}"

設定檔與 .env 的管理見 腳本與 CLI。

下載大檔 ​

python
from pathlib import Path

def download(url, dest: Path, chunk=1 << 20):
    with session.get(url, stream=True, timeout=30) as r:   # stream=True:不一次讀進記憶體
        r.raise_for_status()
        tmp = dest.with_suffix(dest.suffix + ".part")
        with open(tmp, "wb") as f:
            for block in r.iter_content(chunk_size=chunk):
                f.write(block)
        tmp.rename(dest)                                    # 下載完整才改名,避免留下半個檔案

下載參考基因組、資料庫檔後,比對官方提供的 checksum(hashlib.md5 / sha256),確認檔案完整。

除錯檢查表 ​

問題檢查
URL、path 正確嗎?印出 r.url
參數編碼對嗎?用 params=,不要手動拼字串
HTTP 方法對嗎?文件寫 POST 卻用 GET 常回 405
必要標頭都有嗎?Accept、Content-Type、Authorization
回應真的是 JSON 嗎?先看 r.headers["Content-Type"] 再 .json()
是 4xx 還是 5xx?4xx 修請求;5xx / 429 重試

網頁 HTML 的擷取見 Web Scraping;把 API 資料讀成 DataFrame 見 匯入資料。