Libraryの公開APIで、お知らせと法務文書をサイトに配信する仕組み

このサイトのお知らせ、プライバシーポリシー、利用規約、そしてこの技術記事は、リポジトリの中にファイルを持っていません。当社が開発・運用している文書基盤Libraryに原稿を置き、公開APIから取得して表示しています。原稿を直すとサイトの表示も変わり、デプロイは要りません。

使っているエンドポイント

Libraryは組織、リポジトリ、データの三階層で文書を管理します。公開リポジトリは認証なしで読めるので、サイトからは次の2つだけを呼んでいます。

# データ一覧（JSON）
curl -H 'accept: application/json' \
  'https://library-api.txcloud.app/v1beta/repos/quantumbox/news/data-list?page=1&page_size=50'

# 1件の本文（YAML frontmatter付きMarkdown）
curl -H 'accept: text/markdown' \
  'https://library-api.txcloud.app/docs/quantumbox/news/data_01m15xxzekc7pa8m0q507vgm2h/md'

本文のAPIは、Libraryのプロパティをfrontmatterに入れて返します。サイト側はこれを分解して、is_publishがtrueのものだけを表示します。

---
id: data_01m15xxzekc7pa8m0q507vgm2h
title: コーポレートサイトを公開しました
date: 2026-09-01
is_publish: true
---

一覧と本文を分けている理由

一覧のAPIはリッチテキストの冒頭だけを返すので軽く、本文のAPIはMarkdown全文を返します。一覧ページでは前者だけを使い、記事ページで初めて後者を呼びます。記事が増えても一覧の取得コストが本文の長さに引きずられません。

到達できないときの扱い

外部APIに依存するページで一番気を付けたのは、Libraryに到達できないときにサイト全体が遅くならないことです。

• 取得には3秒のタイムアウトを付ける。
• 失敗したら10秒間は再試行せず、すぐに「取得できませんでした」を返す。
• ページは1リクエストで2回描画されることがあるので、遮断がないと待ち時間が倍になる。

const response = await fetch(`${apiBaseUrl}${path}`, {
  headers: { accept },
  signal: AbortSignal.timeout(3000),
});

個別の文書が404を返すのは「到達できない」とは別の状態なので、遮断はしません。

日付をプロパティに持たせなくてもよい

Libraryのdata_idはULIDなので、先頭10文字から作成日時を復元できます。日付プロパティを付け忘れた文書でも、公開日の代わりに作成日時を使えます。お知らせと技術記事では明示的なdateプロパティを優先し、無いときだけこの方法に落とします。

サイト側に残っているもの

サイトのリポジトリが持っているのは、文書の「入れ物」だけです。

同じAPIをAI agentや業務プロダクトからも読めるので、知識の置き場所を用途ごとに分けずに済みます。Libraryそのものの説明はプロダクトページにあります。