API 於星期二上線。我根本不知道誰會使用它。

我正在打造 NewTqnia，一個以英文和阿拉伯文雙語發行的科技媒體，而需求不斷擴張。網站、RSS、JSON API、可嵌入小工具、瀏覽器新分頁頁面、結構化時間軸——每一種都需要以不同的方式傳遞相同的內容。

這引發了一個我至今仍未有明確答案的問題：

如何在不打造六套獨立產品的前提下，支援六種不同的內容傳遞介面？

這不是一則成功故事，而是一系列的權衡，有些有效、有些值得商榷，還有幾項我正積極考慮撤銷。

API：刻意保持精簡

Daily Digest API 的第一個公開版本幾乎什麼都沒做。

curl "https://newtqnia.com/v1/news/today?locale=en&limit=5"

Enter fullscreen mode Exit fullscreen mode

就這樣。僅有 today、latest 兩個查詢參數，無需 API 金鑰。每分鐘 60 次請求、支援 ETag，以及合理的 Cache-Control 設定。

我本可以在第一天就推出分類、標籤、搜尋、推薦和分析等端點。但一個合約不穩定的龐大 API，只不過是碰巧附上公開文件集的私有 API。我想要的是相反的結果：一個即使有人真的拿它來建構應用程式，也不會讓我難堪的小型介面。

尷尬的地方在於：開發者無法要求他們不知道可能存在的端點。因此「等待需求再擴充」是個安全的策略，但可能不是正確的做法。我仍在思考「謹慎地保持精簡」與「過度精簡到毫無用處」之間的界線。

小工具的問題：隔離代價高昂

有些人只是想在自己的網站上顯示標題，而不想撰寫 HTTP 用戶端。因此我建立了一段 script：

<script
  async
  src="https://newtqnia.com/news-widget.js"
  data-count="5"
  data-locale="en"
  data-layout="cards"
  data-orientation="horizontal"
  data-theme="auto"
  data-accent="#03c0f9"
  data-order="latest"
  data-show-image="true"
  data-show-summary="true">
</script>

Enter fullscreen mode Exit fullscreen mode

小工具產生器 會產生這段程式碼，並顯示即時預覽。

沒有人事先警告我的是：每一種隔離策略，都只是把複雜度移到別處。

  • Iframe？ 樣式隔離效果佳，但回應式尺寸調整會變成與宿主頁面之間的協商。
  • Shadow DOM？ 可防止 CSS 外洩，但主題設定與無障礙瀏覽變得棘手。
  • 使用範圍化 CSS 的純 script？ 對嵌入者來說較熟悉，但只要宿主頁面加上一條 !important 規則，版面就會崩壞。

目前我選擇簡單的 script 搭配 data-* 屬性。我不確定這是否是長期解方。如果你曾經發佈過可嵌入小工具，我很想知道：你是否後悔一開始沒有採用 Web Components？

時間軸不是文章

新聞文章描述單一時刻，而時間軸必須說明多年來多個時刻之間的關聯。

我們發佈了如生成式 AI 的演進以及網際網路的歷史等時間軸。內部來看，這些並非長篇文章，而是包含以下欄位的事件集合：

  • 精確或近似日期
  • 事件類型與重要性等級
  • 主要與次要來源
  • 相關連結
  • 事件專屬媒體
  • 雙語標題與替代文字
  • 出處與授權資訊

這讓內容得以重複使用，但也帶來程式碼無法解決的編輯問題。當兩份可靠來源對日期有歧異時該怎麼辦？如何在不損及可信度的情況下標記時間軸為不完整？如何呈現可信但屬次要來源的資料？

我對公開格式也還沒定論。自訂 JSON 容易設計，而 JSON-LD 或既有事件詞彙較難實作，但互通性更好。如果你會從 API 取用時間軸資料，你會偏好哪一種格式？

雙語支援從資料模型開始

阿拉伯文不是「換成不同文字的英文」。它需要 RTL 版面、不同的字體、當地化日期，以及不一定與英文側對稱的介面決策。

對於結構化內容，最簡單的模型是使用明確的雙語欄位：

{
  "title_en": "The Transformer rewrites the architecture of language AI",
  "title_ar": "بنية المحولات تعيد صياغة هندسة الذكاء الاصطناعي اللغوي"
}

Enter fullscreen mode Exit fullscreen mode

當你只有兩種語言時，這種做法容易查詢與驗證。若要擴充至五到十種語言就會變得笨重。正規化的翻譯表可擴展性較佳，但會增加聯結、備援邏輯，以及我目前還不需要的發佈狀態複雜度。

我目前的原則是：在新增第三種語言之前，再重新評估資料模型。過早正規化仍然是過早最佳化。

媒體子系統是意外誕生的

當時間軸開始使用事件專屬圖片時，只儲存單一 URL 已不夠用。一個有用的媒體記錄現在需要：

  • 穩定的內部 ID
  • 處理狀態與回應式變體
  • 尺寸與檔案類型
  • 雙語替代文字與標題
  • 原始來源、出處與授權資訊
  • 與時間軸或單一事件的關聯

圖片會被處理成多種尺寸與格式。事件會引用內部資產，而非外部 URL。這樣可讓無障礙中繼資料與其描述的物件綁定在一起，也避免已發佈頁面依賴第三方主機的正常運作時間。

我無法自動化的部分是：替代文字是否真的有用。驗證只會檢查是否存在，不會檢查其實用性。

散布會建立出處界線

你讓內容越容易移植，就越難控制他人如何使用它。

只回傳標題與 URL，API 幾乎沒有用處；回傳完整文章，則可能招致未標註出處的轉載。摘要是折衷方案，但即使是摘要，也可能被彙整成無臉的摘要流。

目前 API 要求取用者保留文章 URL，並顯示明顯的出處。這是社會契約，而非技術限制。我曾考慮過簽章內容、嚴格條款、計量存取，以及 API 金鑰，但每一種做法都會提高正當實驗的成本。

如果你曾設計過公開內容 API，你是如何決定要開放多少內容的？

如果重來，我會做哪些不同的事

  • 更早建立時間軸資料模型。一開始把時間軸當作文章處理，導致後來必須進行原本可以避免的遷移。
  • 更嚴格地檢視嵌入策略。在你需要在不屬於自己的網站上除錯 CSS 特異性之前，script tag 感覺像是輕鬆的選擇。
  • 記錄 API 的哲學，而不只是端點。開發者需要知道它為何保持精簡，才能決定是否要基於它進行建構。

我目前卡住的問題

如果你要審視這套系統，我很想聽聽你對以下問題的看法：

  1. 範圍蔓延：一個小型 REST API 在什麼情況下需要分類、標籤或搜尋功能？
  2. 推播 vs. 拉取：新新聞的 webhook 是否有用，還是 RSS 已經足以解決這個需求？
  3. 嵌入介面：在 2026 年，data-* script 仍然是好的整合格式嗎？
  4. Web Components：它們真的能解決小工具的隔離問題，還是只是把問題轉移？
  5. 時間軸格式：你會如何在公開 API 中呈現附來源的歷史事件？
  6. 多語模型：什麼是最不複雜、但仍支援未來擴展的模型？
  7. 內容界線：一個公開新聞 API 應該回傳多少文章內容？
  8. 版本控管：在 API 成長之前，我應該先修正哪些快取或合約錯誤？

你可以透過開發者頁面、小工具產生器，以及即時時間軸集合來查看目前的實作。

如果這個系統中有一個部分值得被簡化、替換或完全避開，那會是哪一個？

Enter fullscreen mode Exit fullscreen mode