版本與棄用
路徑版本
API 的主要版本在路徑前綴：https://api.lightup.tech/v1/...
| 變更 | 會不會升版 |
|---|---|
| 新增欄位 | 不升版。你的 client 必須容忍未知欄位 |
| 新增操作 | 不升版 |
| 新增錯誤代碼 | 不升版。遇到沒看過的 error 要當一般失敗處理，不要 crash |
| 拿掉欄位 | 升版 → /v2 |
| 改變既有欄位的語意 | 升版 → /v2 |
能力目錄狀態轉換（planned → preview → ga） |
不升版，但一定會標在能力索引與變更紀錄 |
client 端的相容規則
- 忽略不認得的欄位，不要用嚴格 schema 拒絕整個回應。
- 不要解析不透明字串：分頁
cursor、ETag、x-request-id的形狀隨時可能改，只原封不動傳回去。 - 不要自行拼裝 id。
psn_…、ten_…、acc_…只用平台給過你的值。 - 不要依賴欄位順序，也不要依賴 JSON 物件的鍵順序。
- 不要依賴
message文字，判斷請用error代碼。 - 把契約版本與 operation id 記在你的實作裡，升級前先看變更紀錄。
棄用政策
- 棄用至少 90 天前公告。
- 公告走本文件網站與版本化離線文件包的變更紀錄，不是口頭或私下通知。
- 公告會寫清楚：受影響的操作或欄位、替代方案、生效日期。
planned狀態的能力不會出現在可呼叫的路徑上；它出現在目錄裡只是讓你知道方向，不構成承諾。
契約來源
本文件網站、離線文件包與 API 參考由同一份來源產生：
| 產物 | 來源 |
|---|---|
| API 參考、schema、錯誤代碼 | 版本化的 OpenAPI 文件 |
| 能力目錄（狀態、最低方案） | 平台的能力目錄決定文件 |
| 撤權語意、錯誤語意 | 同上 |
所以網站與離線包不會漂移。如果你發現兩者不一致，那是 bug，請回報。