穩定性與棄用

公開讀取 API 是有版本的。契約版本記錄在所提供的 OpenAPI 文件的 info.version 欄位中，會破壞用戶端的更改是一次版本升級，而不是悄悄的修改。

v1 保證什麼

在 v1 存更新間，它的路徑不會移動，錯誤 code 的含義不會改變，既有條件的狀態碼不會改變，欄位的類型或可空性也不會改變。任何會破壞這些的更改都屬於 v2，而不是 v1 的釋出。

v1 內允許、無需通知的更改

• 新增端點。
• 新增可選的查詢參數。
• 在回應物件上新增欄位。
• 新增回應標頭。
• 在文件中標明為開放式的欄位上新增取值。
• 提高速率限制額度。

需要新的主版本的更改

• 移除欄位。
• 重新命名欄位。
• 更改欄位的類型或可空性。
• 移除錯誤 code，或為其賦予新用途。
• 更改既有條件對應的既有狀態碼。
• 收緊限制。
• 把可選參數變為必填。

你這一方的責任

用戶端必須容忍未知的欄位和未知的取值，並且不得解析面向人的 error 句子。 這是承諾的另一半，沒有它，上面的保證就不成立：拒絕接受自己不認識的欄位的用戶端，會在本頁稱為安全的更改上出錯；解析 error 的用戶端，會在句子被改寫時出錯。請根據 code 分支處理，忽略你不認識的內容，這樣每一次增量更改對你來說都不會有任何代價。

棄用

被棄用的操作或欄位會 在規格中 標記為 deprecated: true，並在其描述中給出原因和替代方案。規格是公告管道，因為它是每個用戶端都已經在讀的唯一產出——這樣程式碼產生器就能直接呈現棄用資訊，而不必有人事先看過某篇部落格文章。

舊的行為會在公告的期限內繼續有效。欄位絕不會被突然移除。

v2 將如何到來

它會作為第二個文件出現在第二個路徑上，與 v1 並行提供——而不是對它的重寫。v1 不會在 v2 釋出的那天停止工作，棄用 v1 本身也是一項遵循同一期限的公告。

規格中的 info.version 是 API 契約的版本，而不是應用程式的釋出版本號：它的主版本就是路徑版本，次版本在上面列出的增量更改發生時遞增，補丁版本在僅修訂文件時遞增。可以從任何回應中把它讀作 X-Motir-Api-Version——快速入門說明了在哪裡看。

本頁是已釋出的承諾。它所依據的內部記錄是 API 決策記錄，第 8 節。