3年ぶりの Notion API メジャーアップデート : hkob の雑記録 (243)

Notion 雑記録 開発記録 API Update

はじめに

hkob の雑記録の第243回目は、9月3日にリリースされる新しい Notion API のバージョン 2025-09-03 について解説します。

田原さんのポスト

安定の田原さんのポストです。Notion API の developers サイトに久々にリリースが紹介されていました。

解説ページはこちらからアクセスできます。

developers.notion.com

このページを要約したものは以下のようになっています。

概要

2025年9月、Notionはデータベース機能を強化するため、単一のデータベースの下に複数のデータソースをサポートする機能をリリースします。これにより、各データソースが異なるプロパティセット（スキーマ）を持つことが可能になります。この変更に伴い、APIバージョンが2022-06-28から2025-09-03にアップデートされます。

主要な変更点

  • データベースは1つ以上のデータソースのコンテナになります
  • 新しい/v1/data_sources APIエンドポイントが導入されます
  • データベースIDの概念は同じままですが、特定のデータソースを参照するには追加のIDが必要になります
  • 既存のデータベース操作の多くは新しいデータソースAPIに移行する必要があります

移行ステップ

  • [ ] ステップ1: データベース下のデータソースIDを取得する呼び出しを追加
  • [ ] ステップ2: ページまたはリレーションを作成する際にデータソースIDを提供
  • [ ] ステップ3: データベースエンドポイントをデータソース同等物に移行
  • [ ] ステップ4: SDK（該当する場合）をアップグレード

影響を受けるAPI

  • データベースのクエリ /v1/databases/:database_id/query → /v1/data_sources/:data_source_id/query
  • データベースの取得 /v1/databases/:database_id → /v1/data_sources/:data_source_id
  • データベースの作成 - 初期データソース情報を含む新しい構造
  • データベースの更新 - 属性によって異なるエンドポイント
  • 検索 - データソースIDとオブジェクトを返すように変更

バージョニングと互換性

  • 2022-06-28APIバージョンは、単一のデータソースを持つデータベースで引き続き動作します
  • 複数のデータソースを持つデータベースに対しては、古いAPIバージョンでエラーが発生します
  • Webhook形式も更新され、APIバージョンに合わせて変更されます
  • 2025-09-03リリース後、古いAPIバージョンは少なくとも6か月間サポート予定

SDK変更

  • TypeScript SDKは新しいバージョン（v5.0.0）がリリースされる予定
  • 新しいnotion.dataSources.*メソッドが導入されます
  • 手動のnotion.request(...)呼び出しを専用メソッドに切り替える必要があります

ここにあるように古い API はしばらく利用可能ですが、データベースに複数のデータソースを繋げてしまった場合には、古い API は使えなくなります。もし、インテグレーションキーを用いたアプリ連携をしているデータベースは、しばらく新しいデータソース機能は使わないようにしておきましょう。アプリ開発者は今後、2025-09-03 に対応したという連絡をしてくれるはずなので、それを待って新しい機能を使い始めるようにするとよいかと思います。

おわりに

新しいデータベース機能を先にリリースしてまうと、それに連携するアプリが一気に使えなくなってしまうので、先に開発者にだけ情報が流されています。開発者の人は早めに datasouce_id に対応したバージョンにアップデートするようにしましょう。NotionRubyMapping も急いで対応するようにしたいと思います。

hkob.notion.site