Domino REST API 1.1.8 發布：CalDAV／CardDAV 實驗登場、PIM 新端點與 cluster failover
Domino REST API（DRAPI）1.1.8 在 2026-09-14 發布。這版新東西不少，最有看頭的是實驗性的 CalDAV／CardDAV 進場，另外還有幾個 PIM 新端點與一個實用的 cluster failover。升級前也有幾個行為改變值得留意，這篇放在後面一節說明。
重點摘要
- 實驗性登場：CalDAV、CardDAV、DXL Extension API（預設關閉）。
- 新端點：
GET pim-v1/attachmentnames/{unid}（撈 mail 文件的附件清單）、POST／PATCH pim-v1/calendarprofile（建/改 calendar profile）。 - 韌性：PIM API 在 primary 不可用時，能改從 cluster member 讀使用者 mail。
- 修正：全 PIM 行事曆端點的問題；Keycloak／OIDC 金鑰輪替問題修好。
- 升級注意（行為改變）：
richTextAs預設改 HTML、POST v1/query/qrp/json強制要forms、GET pim-v1/calendar/profile改名calendarprofile、行事曆項目建/改必須帶 date／timezone／duration——細節見下方〈升級前要注意的行為改變〉。
實驗性登場：CalDAV／CardDAV／DXL Extension API
這版最受矚目的是把三組 API 以實驗性功能引入。三組性質不同：
- CalDAV／CardDAV：標準化的行事曆／通訊錄協定，讓標準用戶端直接連 Domino 的行事曆與通訊錄。官方註明目前僅以 Mozilla Thunderbird 測試過，別預設它跟所有用戶端都相容。
- DXL Extension API：這組是拿來管「設計」（design）的。DXL（Domino XML）官方定義是「一組用來取回與操作資料庫設計的 API」——把 Domino 的設計元素（表單、視圖、agent 等）表示成 XML。這組新 API 就是讓你透過 REST 程式化地存取、修改這些設計元素：把設計匯出成 DXL、或把 DXL 套回資料庫。它跟這版順手改進的唯讀
GET setup-v1/dxl（單純匯出、且會略過壞掉的元素）不同——那個只是匯出，DXL Extension 是更完整的設計管理面。
三組都標「experimental」、預設關閉、未支援 production；要開得在 keepconfig.d 放一個 JSON、把對應的 active（如 dxl）設 true 再重啟 DRAPI。正式用途前務必留意這個定位。
其他新端點與功能
GET pim-v1/attachmentnames/{unid}：從 mail 文件撈附件清單，支援 protocol URL 與內嵌檔案探索。POST／PATCH pim-v1/calendarprofile：建立/更新登入使用者的行事曆 profile；PATCH可只改個別設定。GET v1/lists/{name}加computeTotalCount（預設true）：可控制要不要算總筆數；分類視圖的key參數與scope=documents也改進了。- 其他：
GET v1/info多回 server 的 canonical name；nsfPath跨平台統一用正斜線；表單欄位撈取變快；GET setup-v1/dxl會略過損毀/無法存取的元素以提升可靠度；POST v1/query改善對 view 索引裡 soft-deleted 文件的處理。
韌性與 Admin UI
- PIM 讀 mail 支援 cluster failover：PIM API 在使用者的 primary 郵箱不可用時，能改從 cluster member 取——對做 mail 整合的高可用性是實用改進。
- Admin UI：登入頁與導覽加了 Light／Dark／System 主題切換；Schema Management 加了 Diff View（比對已存 vs 編輯中）；Overview 加了 Consents 管理卡片；表單 Schema 有未存變更提示；ERROR／FATAL 訊息的 console 能見度也提升。
升級前要注意的行為改變
新功能之外，這版也改了幾個既有行為——升上去之前沒注意，原本好好的呼叫可能就回不一樣、或直接壞掉。四個最該確認你的程式有沒有踩到：
richTextAs預設變 HTML：這個查詢參數現在預設輸出 HTML。如果你之前靠「不帶參數時的預設格式」，升上去富文本回傳就變了——依賴預設格式的地方要明確指定。POST v1/query/qrp/json現在強制要forms：forms陣列變成必填屬性。舊的呼叫沒帶forms會失敗——這是最容易讓既有 QRP（Query Results Processor）JSON 查詢直接壞掉的一項。GET pim-v1/calendar/profile改名成GET pim-v1/calendarprofile：端點路徑改了，舊路徑的呼叫要更新。- 行事曆項目要帶齊 date／timezone／duration：建立或更新行事曆項目現在必須指定日期、時區與持續時間。少帶會被擋——時區處理這版也改用 Windows Time Zone Index。
這幾個都不是新功能、是既有行為的改變，升級 checklist 記得掃過。
修正
- 全 PIM 行事曆端點的功能性問題修正。
- Keycloak 與 OIDC 供應商的金鑰輪替（key rotation）問題解決——如果你在 DRAPI 前面接 Keycloak／OIDC 做認證，這個修正值得留意（我們在 DRAPI 對外只吃 JVM truststore 那套 OIDC 實測裡踩過相關的認證細節）。
小結
DRAPI 1.1.8 的看點在新東西——尤其 CalDAV／CardDAV／DXL 實驗性 API（標準協定進場，但預設關、還在實驗），加上 PIM 的附件清單／calendar profile 端點與 cluster failover。升級時別忘了順手掃一遍那四個行為改變（richTextAs 預設 HTML、qrp/json 強制 forms、calendar profile 端點改名、行事曆項目要帶齊時間欄位）。想對照前一版做了什麼，見 DRAPI 1.1.7 發布。