0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@picnic

Notion API大改修：Data Source導入と旧Databasesエンドポイント非推奨化

0
Posted at

はじめに

Notion API バージョン 2026-03-11 で、アーキテクチャレベルの大きな変更が明らかになりました。従来の Databases エンドポイントが非推奨となり、新たに Data Source という概念を中心とした API 設計へ移行が進んでいます。

この変更は、Notion API を利用したインテグレーションを構築・運用しているすべての開発者に影響します。本記事では、何が変わったのか、なぜ重要なのか、そして具体的にどう対応すべきかを整理します。

📌 影響を受ける人

  • Notion API で Databases エンドポイントを利用しているインテグレーション開発者
  • Notion をデータソースとした自動化ツール・ワークフローを運用している人
  • Notion API を使った SaaS や社内ツールを保守している人

変更の全体像

今回の変更は「Data Source を中心とした新アーキテクチャへの再設計」です。旧来の Databases エンドポイントを置き換えるだけでなく、Views・Webhooks・File Uploads といった新機能群も加わり、API の表現力が大幅に拡張されています。

変更内容

1. Data Source オブジェクト・エンドポイントの新設（重要度: 高）

Notion API の中核に Data Source という新しいオブジェクトが追加されました。これは従来の Database を包含・拡張する上位概念と位置づけられています。

項目 詳細
新エンドポイント POST Query a data source / GET List data source templates
オブジェクト型 data_source
ページネーション カーソルベース（has_more / next_cursor）、最大100件/ページ
Webhook 対応 Data sources のイベントを受信可能

Data Source はページネーションの例にも使用されており、Notion が今後のエコシステムの基盤としてこの概念を据えていることがわかります。

2. 旧 Databases エンドポイントの非推奨化（重要度: 高）

⚠️ Breaking Change（将来的）
旧 Databases エンドポイントは Databases (deprecated) として非推奨に分類されています。現時点で即座に動作しなくなるわけではありませんが、今後のバージョンで削除される可能性があるため、早期の移行計画が必要です。

API リファレンスのナビゲーション上で、新旧の Databases エンドポイントが並列して存在する状態になっています。

区分 ステータス 推奨度
Databases（新） Active ✅ 推奨
Databases (deprecated) Deprecated ❌ 非推奨
Data Sources Active ✅ 推奨（新規開発はこちら）

3. Views オブジェクト・エンドポイントの新設（重要度: 中）

データの「見せ方」を API から制御できる Views が追加されました。

エンドポイント メソッド 説明
List views GET ビューの一覧取得
Get view query results GET ビューのクエリ結果取得
Create a view query POST ビューのクエリ作成

これにより、テーブルビュー・カレンダービュー・ボードビューなどの表示形式を API 経由で操作できるようになったと考えられます。

4. Webhook 機能（重要度: 中）

Notion API にネイティブな Webhook 機能が搭載されました。これまでポーリングでしか実現できなかったリアルタイム通知が、Push 型で受け取れるようになります。

対応するイベントカテゴリは以下の通りです:

  • Pages — ページの作成・更新・削除
  • Databases — データベースの変更
  • Data sources — データソースの変更
  • Comments — コメントの追加・編集
  • File uploads — ファイルアップロード
  • Views — ビューの変更

5. File Uploads エンドポイント（重要度: 中）

ファイルアップロードを管理するためのエンドポイントが新設されました。

エンドポイント メソッド 説明
List file uploads GET アップロードされたファイルの一覧取得

Webhook イベントの対象にも含まれており、ファイルのアップロードをトリガーとした自動化ワークフローが構築可能です。

6. その他の新機能

  • Unfurl attribute（リンクプレビュー）: インテグレーションが Notion 内でリッチなリンクプレビューを提供できるオブジェクト
  • API バージョン 2026-03-11: Notion-Version ヘッダーに指定する最新バージョン

影響と対応

今すぐ確認すべきこと

優先度別アクションリスト

🔴 高優先度（既存インテグレーション保守者向け）

  1. 自身のインテグレーションが Databases (deprecated) のエンドポイントを使用しているか確認する
  2. 使用している場合、新しい Databases エンドポイントまたは Data Source API への移行計画を立てる
  3. Notion-Version ヘッダーを 2026-03-11 に更新し、動作確認を行う

🟡 中優先度（新規開発・機能拡張を予定している人向け）

  1. 新規開発では Data Source API をベースに設計する
  2. ポーリングで実装していたリアルタイム連携を Webhook に置き換える検討
  3. Views API を活用し、ビュー操作の自動化を検討する

🟢 低優先度（情報収集段階の人向け）

  1. File Uploads API、Unfurl attribute の公式ドキュメントを確認する
  2. 今後のバージョンアップ情報をウォッチする

コード例

API リクエストの基本形（Before / After）

Before: 旧 Databases エンドポイント

curl -X POST 'https://api.notion.com/v1/databases/{database_id}/query' \
  -H 'Authorization: Bearer {NOTION_API_KEY}' \
  -H 'Notion-Version: 2022-06-28' \
  -H 'Content-Type: application/json' \
  -d '{
    "filter": {
      "property": "Status",
      "select": {
        "equals": "Done"
      }
    }
  }'

After: Data Source エンドポイント（新）

curl -X POST 'https://api.notion.com/v1/data_sources/{data_source_id}/query' \
  -H 'Authorization: Bearer {NOTION_API_KEY}' \
  -H 'Notion-Version: 2026-03-11' \
  -H 'Content-Type: application/json' \
  -d '{
    "filter": {
      "property": "Status",
      "select": {
        "equals": "Done"
      }
    }
  }'

💡 Tips
Notion-Version ヘッダーの値を 2026-03-11 に更新することを忘れずに。バージョンが古いままだと新しいエンドポイントが利用できない場合があります。

Data Source テンプレート一覧の取得

curl 'https://api.notion.com/v1/data_source_templates' \
  -H 'Authorization: Bearer {NOTION_API_KEY}' \
  -H 'Notion-Version: 2026-03-11'

ページネーション処理（JavaScript 例）

async function fetchAllDataSources(notionApiKey) {
  const results = [];
  let hasMore = true;
  let startCursor = undefined;

  while (hasMore) {
    const response = await fetch(
      'https://api.notion.com/v1/data_sources?' +
        new URLSearchParams({
          page_size: '100',
          ...(startCursor && { start_cursor: startCursor }),
        }),
      {
        headers: {
          'Authorization': `Bearer ${notionApiKey}`,
          'Notion-Version': '2026-03-11',
        },
      }
    );

    const data = await response.json();
    results.push(...data.results);
    hasMore = data.has_more;
    startCursor = data.next_cursor;
  }

  return results;
}

まとめ

変更 重要度 対応
Data Source API の新設 🔴 高 新規開発はこちらをベースに設計
旧 Databases の非推奨化 🔴 高 既存インテグレーションの移行計画を策定
Views API の新設 🟡 中 ビュー操作の自動化に活用
Webhook 機能の追加 🟡 中 ポーリングからの置き換えを検討
File Uploads API 🟡 中 ファイル管理の自動化に活用
API バージョン 2026-03-11 🟡 中 ヘッダーの更新を忘れずに

今回の変更は、Notion API の設計思想そのものが Database 中心から Data Source 中心 へシフトしたことを示しています。単なるエンドポイントの追加ではなく、アーキテクチャの根本的な進化です。

既存のインテグレーションを運用している方は、まず旧 Databases エンドポイントの使用箇所を洗い出し、段階的な移行計画を立てることをおすすめします。新規に開発を始める方は、最初から Data Source API + Webhooks の構成で設計することで、将来的な互換性リスクを避けられます。

公式ドキュメントの更新を引き続きウォッチし、非推奨 API の削除時期が発表され次第、移行を完了させましょう。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?