Notion API は、Notion ワークスペース内のページ・データベース・ブロックを外部からプログラム操作するための API だ。Notion を単なるメモツールではなく、データの保管庫・編集 UI として扱えるようになる。
ヘッドレス CMS としての使い方が面白い
よく採用されるのが「Notion をブログやドキュメントサイトのバックエンドにする」構成だ。非エンジニアのメンバーは慣れた Notion で記事を書き、サイト側は API でその内容を取得して表示する。WordPress のような専用 CMS を立てなくても、編集体験のいい管理画面が手に入る。データベースのフィルターやソートも API から指定できるため、公開フラグ付きの記事だけ取る、といった制御も素直だ。
ブロックモデルという壁
つまずきやすいのは、Notion のコンテンツが「ブロック」という入れ子構造で表現される点だ。1 ページ取得しても本文は子ブロックを再帰的に辿らないと組み立てられず、見出し・リスト・画像をそれぞれ別タイプとして扱う必要がある。HTML や Markdown に変換するロジックは自前で書くか、変換ライブラリに頼ることになる。
専用ヘッドレス CMS との使い分け
割り切りも要る。microCMS や Contentful のような専用 CMS と違い、Notion API には型付きのスキーマ保証や配信用 CDN がない。データベースのプロパティはいつでも編集者が変えられるため、サイト側が前提にしているフィールドが消えてビルドが壊れる、という事故が起きうる。少人数のブログや社内ドキュメントなら編集体験の良さが勝つが、編集者が多くスキーマの安定性が重要なメディアでは、専用 CMS のほうが堅い。
速度とリアルタイム性
API にはレート制限があり、大量ページの一括取得は時間がかかる。さらに、変更を即座にプッシュする仕組みはない。サイトに反映するには再ビルドやキャッシュ更新を挟む構成になるため、秒単位のリアルタイム同期が要件の用途には向かない。費用は Notion のプラン料金に含まれ、API 利用自体の追加課金はない。
統合を接続しないと何も見えない
Notion の API は、インテグレーションを個々のページやデータベースに明示的に接続しないとアクセスできない。トークンを発行しただけでは対象が空のままで、「認証は通るのに何も取れない」という状態になる。これは仕様であって不具合ではないが、最初に必ず引っかかる箇所なので、接続作業を手順として明記しておきたい。
親ページに接続すれば配下も対象になりますが、あとから別階層に作られたページは自動では含まれません。運用の中でページが増えていく使い方をする場合、接続範囲が想定どおり広がっているかを定期的に確認する必要があります。
書き込み用途で使うときの現実
Notion を「読む」用途は比較的素直だが、「書く」用途はブロック構造を組み立てる必要があり、リッチテキストの表現を扱うだけでコード量が膨らむ。外部システムから定型のレポートを流し込む程度なら現実的だが、複雑な文書構造を機械的に生成しようとすると割に合わない。書き込みが主目的なら、Notion をデータの保管先にするより、生成した文書を別形式で用意して人間が貼る運用のほうが早いこともある。