第1章 Notion APIの概要と仕組み
Notion API の基本的な役割、REST API としての特徴、利用できる機能と制限について解説します。
Notion APIとは
Notion API は、多機能メモ・ドキュメントツールである Notion を、外部のプログラムから操作するための窓口（インターフェース）です。 Notion の画面を手作業でクリックして行っている作業を、プログラムコードによって自動化できます。
たとえば、毎日決まった時間にタスクを自動作成したり、Web サイトで集めたデータを Notion の表（データベース）に自動登録したり、Notion 内のメモを別のサービスに転送したりすることが可能です。
REST APIとしての特徴
Notion API は、標準的な Web 技術である REST（Representational State Transfer） に基づいて作られています。 HTTP 通信を利用して、世界中どこからでも決まった形式でリクエストを送り、JSON 形式でデータを受け取ります。
- エンドポイント URL: 基本となる URL は
https://api.notion.com/v1/です。 - データ形式: 送信データおよび受信データはすべて JSON（JavaScript Object Notation） 形式で表現されます。
- HTTP メソッド: 取得には
GET、新規作成にはPOST、部分更新にはPATCH、削除にはDELETEを使用します。
Notion APIでできること・できないこと
Notion API を使うことで多くの操作が可能になりますが、セキュリティやシステム設計上の理由から、一部の操作には制限があります。
できること
- データベースの作成、スキーマ（列定義）の変更、行データの検索（クエリ）
- ページの新規作成、タイトルやプロパティの更新、ページのアーカイブ（削除）
- ページ内の本文ブロック（見出し、段落、リスト、画像など）の追加と更新
- ワークスペース内のコンテンツをキーワードで横断検索
- ワークスペース内のユーザー一覧や自分（Bot）の情報取得
できないこと（または制限があること）
- ページの完全削除（ゴミ箱を空にする操作）：API からはアーカイブ状態（ゴミ箱へ移動）にする操作のみ可能です。
- ワークスペース自体の設定変更やメンバーの招待・削除
- Notion AI の直接操作やプロンプト実行
- 1 秒あたりにおよそ 3 回を超える高頻度の連続リクエスト（レートリミットによる制限）
APIバージョン管理
Notion API では、後方互換性を保ちながら改善を続けるために、リクエストヘッダーに API バージョン（日付表記）を指定する仕組みを採用しています。
Notion-Version: 2022-06-28
バージョンを指定することで、Notion 側の機能追加や仕様変更があっても、開発したプログラムが突然動かなくなるトラブルを防げます。
Python の公式 SDK（notion-client）を使用する場合は、適切なバージョンが自動的に設定されます。