作為一名軟體專案經理（PM），撰寫API規格書（API Specification）是一項不能忽視的技能，尤其當專案涉及系統串接或第三方整合時，API規格書就是你與開發團隊之間的溝通橋樑。本文將告訴你如何撰寫一份清晰易懂的API規格書，讓你的文件成為工程師的「心頭好」。
什麼是API規格書？為什麼PM要學？
簡單來說，就是一份詳細說明API運作方式的技術文件，內容涵蓋請求方式、參數格式、回應內容等。
為什麼PM需要懂API？
- 橋樑角色：PM需要協助需求方與工程團隊溝通，理解API串接的需求並明確表達。
- 提高開發效率：清晰的API文件能讓工程師快速上手，減少反覆溝通的時間成本。
- 解決突發問題：遇到API錯誤時，PM能快速釐清問題範圍，協助團隊排除障礙。
你不需要成為API專家，但至少要懂基本邏輯，才能在跨團隊合作中展現專業度，讓專案順利進行。
撰寫API規格書的核心內容
一份好的API規格書，主要包含以下六大內容：1. 基礎資訊
- API名稱：例如「發送獎金API」
- 版本：例如v1.0
- 用途：簡短描述API的功能，例如「用於發送指定金額的獎金給用戶」。
- URL或Endpoint：例如
https://api.example.com/v1/bonus/send
2. 認證與權限
說明API的安全性設定，常見認證機制有：
- API Key：請求時必須攜帶的密鑰。
- OAuth Token：需要通過第三方認證後取得的憑證。
- 無認證：僅限內部測試環境使用。
3. 請求（Request）規格
這部分要說明請求的細節，包含：
- HTTP方法：例如GET、POST、PUT、DELETE。
- 參數格式：
- Header（標頭）：例如Authorization: Bearer Token
- Body（主體）：傳遞資料的格式，通常使用JSON。
範例：
POST /api/v1/bonus/send
Header: {
"Authorization": "Bearer <token>"
}
Body: {
"userId": "12345",
"bonusAmount": 500,
"currency": "TWD"
}
4. 回應（Response）規格
詳細說明API的回應內容，包括成功與失敗時的格式。
範例：成功回應
{
"status": "success",
"transactionId": "TXN98765"
}
範例：失敗回應
{
"status": "error",
"message": "User ID not found"
}
加上狀態碼（Status Code）說明，例如：
- 200：請求成功
- 400：請求錯誤，參數有誤
- 500：伺服器錯誤
5. 錯誤處理
提供常見錯誤的代碼與解釋，方便除錯。例如：
- 40001：缺少必要參數
- 40002：參數格式錯誤
- 50001：系統錯誤，請聯繫管理員
6. 使用範例
提供實際的請求與回應示範，讓工程師可以快速理解並測試。
PM寫API規格書的流程
1. 收集需求
確認API的使用場景、使用者需求，列出需要實現的功能。
- 舉例：發送獎金給玩家 → 確認需要哪些資訊：用戶ID、金額、幣別。
2. 設計API架構
與工程師討論API的結構設計，包含Endpoint名稱、HTTP方法、參數格式等。
3. 撰寫與審核
- 使用工具（如Swagger、Postman）撰寫API文件。
- 與開發團隊進行審核，確認邏輯清晰且符合需求。
4. 版本管理
提供API版本號，避免不同時期的文件混亂，例如v1.0、v1.1。
5. 更新與維護
專案迭代時同步更新API規格書，確保文件準確且可用。
PM對API要摸到多熟？
作為PM，你不需要寫出API，但你必須：
- 理解API基本邏輯：知道什麼是請求、回應、狀態碼等基礎概念。
- 看懂API文件：能夠快速讀懂參數、結構，協助開發排查問題。
- 溝通需求與限制：清楚表達需求，與工程師討論API設計的可能性。
- 掌握測試流程：能使用Postman等工具簡單測試API，確保運作符合預期。
結語
一份清晰易懂的API規格書，對專案的成功至關重要。PM不需要成為寫程式的高手，但必須理解API邏輯、有效撰寫文件，才能成為需求方與工程團隊之間的溝通橋樑。從基礎資訊到錯誤處理，寫好每個細節，讓你的專案更順暢、開發更高效！
