API Spec Review Checklist — 30 個問題抓住 Contract / Error / Version 漏洞

API spec review 不能套用一般 spec review checklist。Endpoint contract、錯誤碼、版本控制、idempotency 是 API 獨有的痛點。這篇給你一份能在會議前 20 分鐘掃完的 API spec 專用 checklist。

必問 5 題

1. 每個 endpoint 用什麼 HTTP method？ GET / POST / PUT / PATCH / DELETE 各有語意
2. Path 設計符合 REST？ /users/{id}/orders 不是 /getUserOrders?uid=
3. Request body schema 完整嗎？ 每欄型別、必填、長度、格式
4. Response schema 完整嗎？ 含 success / error 兩種
5. 嵌套物件結構是否合理？ Flat vs Nested 取捨

反例（spec 太薄）

POST /orders
Request: { items, total }
Response: { id, status }

問題：

• items 是什麼結構？array of object？欄位有什麼？
• total 包稅嗎？幣別？
• id 是 int 還 string？UUID？
• status 有哪些可能值？

好例子

POST /api/v1/orders
Request:
  Content-Type: application/json
  Body:
    items:
      type: array
      minItems: 1
      maxItems: 50
      item:
        sku: string (3-20 chars, /^[A-Z0-9-]+$/)
        qty: integer (1-99)
    payment_method: enum [credit_card, paypal, apple_pay]
    coupon_code: string (optional, 6-12 chars)
    shipping_address: <ShippingAddress object>
Response 201:
  id: string (UUID v4)
  status: enum [pending, confirmed]
  total: number (含稅，TWD)
  estimated_delivery: string (ISO 8601)

必問 6 題

1. 每個 endpoint 可能回什麼 HTTP status？ 200 / 201 / 400 / 401 / 403 / 404 / 409 / 422 / 429 / 500
2. 錯誤 payload 結構長什麼樣？ 統一格式還是各 endpoint 不同？
3. 錯誤碼有列表嗎？ ERR_INSUFFICIENT_BALANCE 還是 error.code = 1042？
4. 錯誤訊息要不要多語系？ 後端傳 code 還是已翻譯字串？
5. 5xx 何時發生？什麼時候是 4xx vs 5xx 邊界？
6. Retry 策略寫了嗎？ 哪些錯能 retry，哪些不行（idempotency）

標準錯誤 payload 建議

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Your balance is too low for this purchase",
    "details": {
      "current_balance": 100,
      "required": 500,
      "currency": "TWD"
    },
    "trace_id": "abc-123-def",
    "doc_url": "https://docs.example.com/errors/INSUFFICIENT_BALANCE"
  }
}

code 給程式判斷、message 給開發 debug、details 給 UI 顯示、trace_id 給 support 查、doc_url 給開發者學習。統一格式整 API 共用。

HTTP status 對照（常被搞混）

QA 在 spec review 看到所有錯誤都用 400 → 舉手問清楚。

必問 5 題

1. 認證方式？ Bearer JWT / OAuth / API key / Session cookie
2. Token 怎麼取得？怎麼 refresh？ TTL？
3. 每個 endpoint 需要什麼 scope / role？
4. 多租戶隔離怎麼做？ Tenant ID 在 token、URL、還是 header？
5. Service-to-service 怎麼認證？ 跟使用者 API 一樣 token 嗎？

常見漏洞

• Token 過期沒明確錯誤：401 但沒告訴你是 token 過期還是無效 → 客戶端不知道要 refresh 還是重新登入
• 403 vs 404 混用：為了防資訊洩漏（不告訴你「資源存在但你沒權限」），有時 spec 寫 403、有時 404 → 要統一
• 跨租戶資料：GET /users/{id} 沒驗 caller 跟 user 同租戶 → 嚴重資安

必問 5 題

1. 版本怎麼標？ URL（/v1/）、Header（API-Version: 2）、Accept（application/vnd.example.v1+json）
2. 什麼算 breaking change？ 改欄位型別、刪欄位、改 enum 值、改錯誤碼
3. Breaking change 的廢棄流程？ 多久 deprecation period？怎麼通知？
4. Backward compatibility 保證多久？
5. 新欄位怎麼加？ 預設值？optional？

Non-breaking vs Breaking

Deprecation 標準流程

v1: 上線
v2: 上線（v1 仍可用，response 加 Deprecation header）
v1: 6 個月後正式下架

API spec 沒寫 deprecation policy = 等於沒有 versioning。

必問 5 題

1. 有 rate limit 嗎？ 多少 req / sec / user / IP？回什麼 429 payload？
2. List endpoint 有分頁嗎？ Cursor-based 還 offset？最大 page size？
3. Cache header 怎麼設？ Cache-Control、ETag、Last-Modified
4. 大檔案上傳 / 下載？ Streaming？multipart？S3 pre-signed URL？
5. 同步 vs 非同步？ Long-running task 要不要拆 job + status endpoint？

Pagination 設計差異

建議：使用者 feed 用 cursor、後台管理頁用 offset。spec 沒寫的話 → 追問。

必問 4 題

1. POST 是 idempotent 嗎？ 同 payload 打兩次會建兩筆？怎麼防止？
2. 時區處理？ API 用 UTC 還 local？輸入接受哪些格式？
3. 敏感資料？ Email、phone、身分證 — masked 還是明碼？日誌會印嗎？
4. 欄位 nullable 規則？ null vs missing vs empty string

Idempotency 實作標準

POST /orders
Headers:
  Idempotency-Key: <UUID>  # 客戶端產生

Server 行為:
  - 第一次：建單、儲存 (Idempotency-Key, order_id)
  - 重複請求：回傳一樣的 order_id、不重複建單
  - Key TTL：24 hr（避免無限儲存）

spec 沒寫 Idempotency-Key 流程 → POST 重複扣款是時間問題。

打勾用，會議前 20 分鐘掃完：

Contract

• [ ] 每個 endpoint 的 HTTP method 對嗎？
• [ ] Path 符合 REST 慣例（資源 / 動作分離）？
• [ ] Request schema 含每欄型別、必填、長度、格式？
• [ ] Response schema 含 success / error 兩種？
• [ ] 巢狀物件結構合理？

Error

• [ ] 列出每個 endpoint 可能的 HTTP status？
• [ ] 錯誤 payload 統一格式？
• [ ] 錯誤碼有完整列表？
• [ ] 錯誤訊息多語系策略？
• [ ] 4xx vs 5xx 邊界清楚？
• [ ] Retry 策略寫了嗎？

Auth

• [ ] 認證方式明確？
• [ ] Token 取得 / refresh 流程？
• [ ] Endpoint scope / role 列表？
• [ ] 多租戶隔離方式？
• [ ] Service-to-service auth？

Versioning

• [ ] 版本標示方式？
• [ ] Breaking change 定義？
• [ ] Deprecation period？
• [ ] Backward compatibility 保證？
• [ ] 新欄位加法？

Performance

• [ ] Rate limit 數字？
• [ ] List 分頁方式？
• [ ] Cache header 策略？
• [ ] 大檔案處理？
• [ ] 同步 vs 非同步？

Data

• [ ] POST idempotent？
• [ ] 時區處理？
• [ ] 敏感資料是否 masked？
• [ ] Nullable 規則？

API spec 用 OpenAPI 3.0 寫的話，很多面向有結構化欄位強制你填：

• required — 必填
• enum — 限制值
• format — date-time、email、uri
• pattern — regex
• minimum/maximum、minLength/maxLength

QA 看 OpenAPI spec 的優勢：

1. 用 openapi-generator 自動生 client → 對 contract
2. 用 Dredd / Schemathesis 自動測 contract → 抓 spec 與實作差異
3. UI（Swagger UI / Redoc）讓 PM / 前端都能 review

沒用 OpenAPI 的話，這 30 題人工問。

1. 「依前端需求調整」 — 沒設計、見步行步、最後變亂麻
2. 「跟 v1 一樣」 — v1 漏的東西繼承到 v2
3. 「等開發完再寫 doc」 — 永遠不會寫
4. 「Postman collection 就是文件」 — Postman 不是 contract spec
5. 錯誤碼用整數 — error_code: 1042 整數沒可讀性、難維護
6. 欄位命名混亂 — user_id / userId / uid 三種寫法都出現
7. 時間用 unix timestamp — 客戶端跨時區算錯，應該用 ISO 8601 string

關鍵：QA review 不過 → 退回 backend 補。前後端不該並行開發到一半才發現 contract 沒對齊。

API spec review 是 QA 影響力放大器 — 一個漏洞在 spec 階段抓到，省下後續前端、後端、客戶端 SDK、文件全要改的時間。30 題打勾掃過、會議裡用問題形式問 PM/Backend，省的不只你的時間。