APIは火曜日に公開された。誰が使うのかはわからなかった。

私は英語とアラビア語のバイリンガル技術メディア、NewTqniaを構築しており、要件はどんどん拡大していった。ウェブサイト、RSS、JSON API、埋め込み可能なウィジェット、ブラウザの新規タブページ、構造化タイムライン——いずれも同じコンテンツを異なる形で配信する必要があった。

それにより、今でも明確な答えのない疑問が生まれた：

どうすれば6つの配信サーフェスを、6つの独立したプロダクトを構築せずにサポートできるのか？

これは成功談ではない。トレードオフの集まりであり、一部は機能し、一部は疑問があり、そして積極的に取り消そうとしているものがいくつかある。

API：意図的に小さく

Daily Digest APIの初回公開バージョンは、ほとんど何もしない。

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

フルスクリーン表示 フルスクリーン表示を終了

それだけだ。today、latest、2つのクエリパラメータ、APIキーは不要。1分あたり60リクエスト、ETagサポート、適切なCache-Control。

初日からカテゴリ、タグ、検索、レコメンデーション、アナリティクスエンドポイントを提供することもできた。しかし、契約が不安定な大規模APIは、たまたま公開ドキュメントがあるだけのプライベートAPIに過ぎない。私はその逆が欲しかった。誰かが実際に構築したとしても恥をかかない、小さなサーフェス。

厄介な点は？開発者は可能かどうかわからないエンドポイントを要求できない。だから「需要を待つ」というのは安全な戦略だが、おそらく正しいものではない。「慎重に小さく」と「無駄に小さく」の境界線がどこにあるのか、今も模索中だ。

ウィジェットの問題：分離は高コスト

HTTPクライアントを書かずに自分のサイトにヘッドラインを表示したい人もいる。そこでスクリプトを作成した：

<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>

フルスクリーン表示 フルスクリーン表示を終了

ウィジェットビルダーがこれを生成し、ライブプレビューを表示する。

誰も警告してくれなかった点はこれだ：あらゆる分離戦略は、複雑性をどこかに移動させる。

  • Iframe？ 強力なスタイル分離だが、レスポンシブサイズはホストページとの交渉になる。
  • Shadow DOM？ CSSリークから保護するが、テーマ設定とアクセシビリティの走査が奇妙になる。
  • スコープ付きCSS付きのプレーンなスクリプト？ 埋め込み側には馴染みがあるが、ホスト側で1つの!importantルールが追加されただけでレイアウトが崩れる。

今はシンプルなスクリプトとdata-*属性を採用している。長期的な回答だとは思っていない。埋め込み可能なウィジェットをリリースしたことがあるなら、ぜひ知りたい。最初からWeb Componentsを使わなかったことを後悔しただろうか？

タイムラインは記事ではない

ニュース記事は一瞬を記述する。タイムラインは、数年にわたる瞬間の関係を説明しなければならない。

私たちは生成AIの進化やインターネットの歴史などのタイムラインを公開している。内部的には、これらは長い記事ではない。以下のようなフィールドを持つイベントのコレクションだ：

  • 正確またはおおよその日付
  • イベントタイプと重要度レベル
  • 一次および二次ソース
  • 関連リンク
  • イベント固有のメディア
  • バイリンガルのキャプションと代替テキスト
  • 帰属とライセンス

これによりコンテンツは再利用可能になるが、コードでは解決できない編集上の問題も生じる。2つの信頼できるソースが日付について意見を異にしたらどうするか？タイムラインを不完全とマークしつつ信頼性を損なわないようにするには？信頼できるが二次的なソースをどう表現するか？

公開形式についても確信がない。カスタムJSONは設計しやすい。JSON-LDや既存のイベント語彙は難しいが相互運用性が高い。APIからタイムラインデータを消費する場合、どちらを好むだろうか？

バイリンガルサポートはデータモデルから始まる

アラビア語は「単語が違うだけの英語」ではない。RTLレイアウト、異なるタイポグラフィ、ローカライズされた日付、そして英語側と必ずしも一致しないインターフェース決定が必要になる。

構造化コンテンツでは、最もシンプルなモデルは明示的なバイリンガルフィールドだ：

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

フルスクリーン表示 フルスクリーン表示を終了

これはちょうど2つの言語がある場合、クエリとバリデーションが容易になる。5つや10つになると醜くなる。正規化された翻訳テーブルの方が拡張性があるが、結合、フォールバックロジック、パブリッシング状態の複雑さが加わり、今のところ必要ない。

現在のルール：3つ目の言語を追加する前にモデルを再検討する。それまではしない。早すぎる正規化は、まだ早すぎる最適化だ。

メディアは偶然、サブシステムになった

タイムラインがイベント固有の画像を使い始めると、単一のURLを保存するだけでは不十分になった。役立つメディアレコードには今、以下が必要だ：

  • 安定した内部ID
  • 処理ステータスとレスポンシブバリアント
  • 寸法とファイルタイプ
  • バイリンガルの代替テキストとキャプション
  • 元のソース、帰属、ライセンス
  • タイムラインまたは個別のイベントとの関係

画像は複数のサイズとフォーマットに処理される。イベントは外部URLではなく内部アセットを参照する。これによりアクセシビリティメタデータが記述対象のものに紐付けられ、サードパーティホストの稼働時間に公開ページが結びつくのを防ぐ。

自動化できない部分：代替テキストが実際に良いかどうか。バリデーションは存在をチェックする。有用性をチェックするわけではない。

配信は帰属の境界を生む

コンテンツをポータブルにするほど、どのように使われるかの制御が弱まる。

タイトルとURLのみを返す場合、APIはほとんど役に立たない。完全な記事を返すと、無帰属の再出版を招くことになる。要約は中間的な選択肢だが、要約でさえ顔の見えないフィードに集約される。

現在、APIは利用者に記事URLを保持し、目に見える帰属を表示するよう求めている。それは技術的な契約ではなく、社会的な契約だ。署名付きコンテンツ、より厳格な利用規約、従量制アクセス、APIキーを検討した。いずれも正当な実験のコストを押し上げる。

公開コンテンツAPIを設計したことがあるなら、どれだけ提供するかをどのように決めただろうか？

私が違ったやり方をするなら

  • タイムラインデータモデルをより早くから始める。タイムラインを最初に記事として扱ったことで、避けられたかもしれない移行が発生した。
  • 埋め込み戦略をもっと厳しく検討する。scriptタグは、自分が管理していないサイトでCSSの詳細度をデバッグするまでは簡単な道のように感じる。
  • APIのエンドポイントだけでなく、その哲学を文書化する。開発者は、それに乗るかどうかを決める前に、なぜ小さいのかを知る必要がある。

私が悩んでいる質問

このシステムをレビューするなら、以下の点について意見を聞きたい：

  1. スコープの拡大：小規模なREST APIがカテゴリ、タグ、検索を必要とするのはどの時点か？
  2. プッシュ vs. プル：新着記事向けのwebhookは有用だろうか、それともRSSで十分か？
  3. 埋め込みインターフェース：data-*スクリプトは2026年でも良い統合形式だろうか？
  4. Web Components：ウィジェットの分離問題を実際に解決するのか、それとも単に問題を移動させるだけなのか？
  5. タイムライン形式：公開APIで出典付きの歴史的イベントをどのように表現するか？
  6. 多言語モデル：将来の拡張をサポートしつつ、最も複雑でないモデルは何か？
  7. コンテンツの境界：公開ニュースAPIは記事コンテンツをどれだけ返すべきか？
  8. バージョン管理：APIが大きくなる前に修正すべきキャッシュや契約のミスはどれか？

現在の実装は、開発者ページ、ウィジェットビルダー、およびライブのタイムラインコレクションから触ることができる。

このシステムの中で、簡素化、置き換え、または完全に避けるべき部分があるとしたら、それはどれだろうか？

フルスクリーン表示 フルスクリーン表示を終了