版本與淘汰政策

版本寫在路徑裡

每個資料集端點都在 /v2 之下。新的主要版本會以新的路徑前綴出現,而不是在既有前綴後面改行為——所以只要 /v2 還在回應,固定打 /v2 的呼叫端就會一直拿到 /v2 的語意。

我們把什麼算作破壞性變更

判準是:一個原本正確的整合,會不會在自己完全沒改動的情況下變得不正確。如果會,那就是破壞性變更,不會在同一個版本裡出貨。

• 移除欄位,或改變它的型別、單位或意義。
• 移除端點,或縮限它能接受的輸入。
• 改變一列的粒度——也就是一列代表什麼。
• 把選填參數改成必填。
• 不算破壞性:新增欄位、新增端點、新增選填參數,或放寬既有參數的接受範圍。請寬鬆解析——新欄位是會出現的。

撤除前的通知期

被標記淘汰的端點,自公告起至少繼續回應 90 天。在這段期間它的行為完全不變——淘汰是對未來的陳述,不是對回應的改動。標記為 building 等級的資料集不適用:那個等級的意思就是它還沒穩定。

每個回應都帶著它的額度狀態

每個回應都帶著三個標準標頭,不論那次呼叫有沒有帶金鑰——包括你在沒帶金鑰時去打需要金鑰的資料集所收到的 401。它們遵循 draft-ietf-httpapi-ratelimit-headers,所以 HTTP 客戶端自己的退避邏輯讀得懂,不需要先認識我們。

• `RateLimit-Reset` 是**秒數**,不是絕對時間。絕對時間要求雙方時鐘一致,而一個慢五分鐘的客戶端會據此提早重試,把一次 429 變成穩定的迴圈。
• 429 另外會帶 `Retry-After`。RateLimit-* 還是草案,只送新標頭等於對舊客戶端什麼都沒說,所以兩組一起送。

RateLimit-Limit      quota for this windowRateLimit-Remaining  calls leftRateLimit-Reset      seconds until reset  (delta-seconds, NOT a timestamp)Retry-After          sent additionally on 429

撤除會怎麼公告

機制已經就位:`Deprecation` 帶端點被宣告棄用的時刻,`Sunset` 帶它停止回應的時刻(RFC 9745 / RFC 8594),並以 `Link rel="deprecation"` 指回本頁。機器客戶端應該讀這些標頭,而不是來盯這一頁。

目前沒有任何端點在退役,所以你今天不會在回應上看到這些標頭。**沒有它們本身就是訊息**——機制刻意在需要之前就先建好,因為在退役當天才加上標頭,對一個在公告之前就寫好的整合來說等於毫無預警。

沒有登記退役的端點不會帶空的標頭,而是完全不帶。一個沒有值的 `Sunset:` 會讓嚴格的解析器出錯,而它表達的東西和不送是一樣的。