LightUp 第三方 API 契約已定案・端點已上線 v1.0.0 · 707394544381

版本與棄用

路徑版本

API 的主要版本在路徑前綴:https://api.lightup.tech/v1/...

變更 會不會升版
新增欄位 不升版。你的 client 必須容忍未知欄位
新增操作 不升版
新增錯誤代碼 不升版。遇到沒看過的 error 要當一般失敗處理,不要 crash
拿掉欄位 升版 → /v2
改變既有欄位的語意 升版 → /v2
能力目錄狀態轉換(planned → preview → ga) 不升版,但一定會標在能力索引與變更紀錄

client 端的相容規則

  1. 忽略不認得的欄位,不要用嚴格 schema 拒絕整個回應。
  2. 不要解析不透明字串:分頁 cursor、ETag、x-request-id 的形狀隨時可能改,只原封不動傳回去。
  3. 不要自行拼裝 id。psn_…、ten_…、acc_… 只用平台給過你的值。
  4. 不要依賴欄位順序,也不要依賴 JSON 物件的鍵順序。
  5. 不要依賴 message 文字,判斷請用 error 代碼。
  6. 把契約版本與 operation id 記在你的實作裡,升級前先看變更紀錄。

棄用政策

契約來源

本文件網站、離線文件包與 API 參考由同一份來源產生:

產物 來源
API 參考、schema、錯誤代碼 版本化的 OpenAPI 文件
能力目錄(狀態、最低方案) 平台的能力目錄決定文件
撤權語意、錯誤語意 同上

所以網站與離線包不會漂移。如果你發現兩者不一致,那是 bug,請回報。