Content Delivery API

Content Delivery API 是專為外部前端與流動裝置應用程式設計的公開 HTTP API，直接掛載於您網站專屬的網址下。當您在資料集合、網誌、頁面管理或網上表單發佈內容後，任何前端框架（Next.js、Astro、Remix、Nuxt、SvelteKit）均可直接呼叫，無需在前端保管金鑰，並由全球邊緣快取提供毫秒級回應。

完整端點、參數與錯誤碼參考（SSOT）：所有端點路徑、查詢參數、回應結構、速率限制 Header 與錯誤碼，皆由 OpenAPI 3.1 規格自動產生於 Content Delivery API 參考頁（您亦可直接從您的網站下載 https://{您的網站}/api/v1/openapi.json）。本文專注說明平台層的設計概念。

三套 API 的分工

兩層網址：為什麼推薦使用永久系統網址？

您的網站同時擁有兩種可呼叫 Content Delivery API 的網址：

1. 永久系統網址（https://s-xxxxxxxxxxxx.kanorio.com/api/v1）：建站當下即配發，永久不變。即使您尚未發佈 Kanorio 託管頁面（僅在「網站設定 › 開發者」開啟「未發佈網站時仍啟用 API 服務」），或未來將自訂網域的 DNS 指向 Vercel／Cloudflare Pages，這組系統網址依然永遠有效。
2. 公開子網域或自訂網域（https://您的子網域.kanorio.com/api/v1）：當託管網站已發佈時，亦可直接透過公開網域呼叫。

搜尋引擎防護：所有 /api/v1/* 回應皆自動帶上 X-Robots-Tag: noindex Header，防止搜尋引擎將 JSON 端點視為網頁收錄，從而稀釋您網站的 SEO 權重。

為什麼採用頂層 assets 媒體對照表？

在許多傳統 CMS 中，圖片欄位若僅儲存一串 ID，前端必須發送第二次請求才能獲取網址；若直接將圖片網址寫死在欄位內，當站主在媒體庫替換圖片或修改替代文字（alt）時，所有文章內的舊網址就會失準。

因此，Kanorio 在 /collections/{key}/items、/pages/{slug} 與 /globals/* 的回應頂層統一附上 assets 對照表：

• 欄位值保持簡潔：項目內的 image、file 欄位維持儲存 assetId 字串（gallery 儲存 assetId[]）。
• 一次解析所有引用媒體：頂層 assets[assetId] 自動附上最新的公開 CDN 網址（url）、原始寬高（width、height）、替代文字（alt）、檔案類型，以及 16px WebP 模糊佔位圖（placeholder Data URL）。
• 響應式圖片免設定：公開圖片網址可直接加上 /w=400、/w=800、/w=1200、/w=1600 或 /w=1920 取得對應寬度的最佳化圖片，搭配 placeholder 即可在 Next.js <Image blurDataURL={...} /> 實現零 CLS 載入。

跨網域讀取（CORS）與草稿預覽權杖（knr_pv_）

1. 允許的來源（CORS 白名單）

• 若您在 Next.js Server Component、Astro 建置階段或後端伺服器呼叫 API，屬於伺服器對伺服器請求，無需設定 CORS。
• 若您從外部網站的瀏覽器端直接 fetch（例如即時搜尋或提交表單），請前往後台「網站設定 › 開發者」將外部前端的 Origin（如 https://www.example.com）加入「允許的來源」。本機開發 http://localhost:* 預設永遠允許。
• 重要觀念：CORS 白名單僅控制瀏覽器是否放行跨源讀取，並非授權邊界；未發佈的草稿在資料庫查詢層即完全隔離。

2. 在自建前端安全預覽草稿（X-Kanorio-Preview）

當編輯者在後台修改了文章或頁面草稿、想在外部前端預覽尚未發佈的畫面時：

• 前往「網站設定 › 開發者」建立一把 knr_pv_ 開頭的唯讀預覽權杖（或由 AI 呼叫 site.create_preview_token）。
• 在您外部前端的伺服器端（如 Next.js Draft Mode）帶上 Header X-Kanorio-Preview: knr_pv_您的預覽權杖（或使用 @kanorio/sdk 的 previewToken 選項）。
• 預覽請求會在邊緣節點直接完成 HMAC 驗簽、旁路所有公開快取（Cache-Control: private, no-store），並回傳最新草稿內容。

版本鍵邊緣快取與 X-Kanorio-Cache-Tags

Content Delivery API 不限制每月讀取次數、亦不收取 API 流量費，關鍵在於兩層版本鍵快取與快取標籤設計：

1. 自動版本推進：每當您在後台或透過 AI 發佈任何內容，網站的 publicVersion 會自動推進，邊緣快取在數秒內立即切換至新版，同時支援弱 ETag 與 If-None-Match（內容未變時回傳 304 Not Modified）。
2. 精準快取標籤（X-Kanorio-Cache-Tags）：每個回應皆會帶上結構化標籤（如 site:{siteId}、collection:blog、item:{itemId}、pages、globals、redirects），與 Payload 中的 data.cacheTags 完全對齊，一行程式碼即可在 Next.js 完成按需更新。

相關文件