在前段時間的練習中，我已經學會了怎麼呼叫 API、分析資料，甚至完成整個資料處理的流程。

但如果想設計一個真正可以讓別人使用的 API，就不只是會傳送資料這麼簡單了。還需要考慮更多重要的事情，比如如何管理不同的版本（版本控制）、限制使用者的請求次數（流量限制，Rate Limit），還有怎麼寫清楚易懂的使用說明文件。

今天，我們要一起學習 API 設計中常見的幾個重要概念和好的做法，讓我們未來可以做出更專業、更好用的 API。

為什麼要學 API 設計原則？

學習 API 設計原則可以讓 API 穩定地成長，不會因為改動而影響原本使用 API 的程式，還能確保在使用人數多、流量大的情況下，API 依然保持穩定，避免伺服器過載。同時，良好的設計原則有助於團隊建立一致的風格和標準，讓程式更容易維護，也使團隊溝通更加順暢。

一、Rate Limit（使用頻率限制）

什麼是 Rate Limit？

Rate Limit 是伺服器用來控制每個使用者，在一定時間內最多能發送多少次請求的規則。

這樣做有兩個主要目的：

• 保護伺服器不會被人大量或惡意使用，避免當機或壞掉。

• 確保所有使用者都能公平地使用伺服器資源，不會有某個人獨占太多。

常見錯誤訊息

當我們看到 429 Too Many Requests 這個錯誤，意思是我們在短時間內對伺服器發送的請求太多，超過了伺服器設定的使用次數限制。

通常伺服器會告訴我們還要等多久才能再試一次，這個時間會放在標頭裡面，叫做 Retry-After。
比如說：

Retry-After: 30

就是告訴我們需要等待 30 秒後才能重新發送請求。這樣可以保護伺服器不會被過度使用，確保大家都有公平的使用機會。

如何在程式中處理？

當程式收到 429 錯誤，表示我們發送請求太頻繁了，需要暫時停止。

處理方法：

• 如果伺服器告訴我們 Retry-After 需要等多久，就照著這個時間等，之後再重新嘗試。

• 如果沒有 Retry-After，可以用指數退避的方法，每次等待的時間變長，再繼續嘗試，避免太快連續重試。

• 不要同時用很多線程，也就是多個程序，一直發送請求，這樣會造成伺服器負擔突然增加，產生雪崩效應，讓伺服器更容易崩潰。

二、API 版本控制（Versioning）

為什麼要版本控制？

當 API 上線後，會有很多人開始使用它。如果我們直接改變資料欄位或者回傳的格式，原本使用舊版本 API 的程式可能會出錯或無法運作。為了避免這種問題，我們會用版本控制來管理 API。

這樣可以確保：

• 新版本和舊版本的 API 能同時存在，互不影響。

• 使用者有足夠的時間修改他們的程式碼來配合新的版本。

常見的版本控制方法

URL 版本控制

例子： https://api.example.com/v1/users

優點：這種方式直覺又容易看出版本號，使用者很容易辨識自己用的是哪個版本。

缺點：每次 API 改版時，要複製並維護整組新的網址路由，可能會增加管理複雜度。

標頭（Header）版本控制

例子：請求中帶有 Accept: application/vnd.example.v2+json 這種標頭來指定版本。

優點：網址比較簡潔，可以針對細微的版本差異做控制。

缺點：這種方式不容易讓初學者注意到或理解，需要更多說明，且對使用者要求較高。

設計原則

向後相容：
當我們在 API 裡新增欄位或功能時，不應該影響原本用舊版本的使用者，他們的程式仍要正常運作。

破壞性改動開新版本：
如果我們要做會影響舊使用者的重大改變，應該建立一個新的版本，讓使用者自行選擇升級。

明確公告：
要清楚告訴使用者舊版本的 API 會在什麼時候停止提供服務，讓他們有足夠的時間準備與調整。

三、API 文件的重要性

為什麼文件這麼重要？

API 沒有像一般軟體那樣的圖形操作介面，所以使用者只能透過文件來了解怎麼使用這個 API。如果文件寫得清楚、詳細，就能幫助開發者快速學會怎麼跟 API 溝通，節省摸索時間。

好的文件也能減少使用者遇到問題時需要求助客服或技術支援的次數，讓整個服務更順暢、更有效率。簡單來說，清楚的文件是讓 API 被大家放心使用的關鍵。

一份好的文件要有什麼？

快速開始（Quick Start）：
提供簡單明瞭的教學，讓使用者能快速寫出第一個 API 請求。

範例請求與回應：
展示真實的請求範例和伺服器回傳的資料，讓使用者知道怎麼發出請求以及能得到什麼結果。

基本授權方式：
說明怎麼使用 API Key 或 Token 等授權方法來驗證身份。

錯誤代碼說明：
清楚列出所有可能遇到的錯誤，每個錯誤都要有代碼（code）、錯誤訊息（message）、產生原因以及建議的解決方法。

Rate Limit 說明：
告訴使用者 API 的使用次數限制（請求上限）和如果超過限制，應該怎麼重試。

版本與更新歷史：
標明目前可用的 API 版本，還有哪些版本即將停止支援，讓使用者知道何時需要更新程式。

範例回應格式：
說明回傳的 JSON 結構和每個欄位的意義，方便使用者直接套用在自己的程式裡。

這些內容能幫助使用者快速理解並正確使用 API，降低使用上的困難。

今日總結

今天我學會了三個在 API 設計中非常重要的觀念：Rate Limit、版本控制和文件撰寫。這些觀念不只讓 API 可以正常使用，還能確保它長時間穩定運作，不容易出問題。未來無論是自己設計或使用 API，我都會好好遵守這些原則，這樣才能做好 API，讓使用者有更好的體驗。