はじめに

参加中のインターンで、Notion APIをPostmanから制御する機会がありました。
せっかくなので、入門した時の覚書を記事として書き直します。

Notionについて

NotionはWebやデスクトップで使える、柔軟なノートアプリケーションです。EvernoteやOneNoteと同じようなものですね。

Notionでは データベース機能（Notion DB） が特徴的で、表、カンバンボード、カレンダー、リストなど、さまざまなビューを使用して情報を整理できます。
このDBはリレーショナルデータベースの要素を持ち、異なるデータベース間の関係をリンクさせることが可能だったりと、けっこう便利です。

これは主観ですが、ハッカソンなどの学生プロジェクトの管理ツールとしても多く使われているほか、個人的なノートアプリとして使用しつつ、共有するときは記事として共有できるので、学生の間では結構使われていたりします。

Notion APIについて

Notion API は、外部アプリケーションやサービスがNotionのデータにアクセスし、操作することを可能にするインタフェースです。このAPIを利用することで、ユーザーはNotion内のコンテンツをプログラム的に管理したり、他のアプリケーションと連携したりできます。具体的には、

データベースの操作
ページの操作
ワークスペース内のユーザー情報の取得

などができます。
これら機能の実装には、NotionのWebサイトからインテグレーションを作成する必要があります。

インテグレーションとは

インテグレーションは、外部アプリケーションがNotionと通信するための機能です。これはBotというより外部と内部をつなぐ鍵のようなもので、読み書きの権限やワークスペースへのアクセス権などはこのインテグレーションを介して設定されています。

インテグレーションには二種類あり、

インターナル（Internal、非公開）
パブリック（Public、公開）

の二つがあります。デフォルトではインターナルですね。

APIを制御してみる

それでは、簡単にAPIに触れてみたいと思います。
以下の公式記事が参考になると思うので、分かりづらればこちらをご覧ください。

前提として、Notionアカウントを持っていることを確認してください。

そしたら、テスト用にDBを持ったページを作成しておきます。

今回はこのDBに対して新しいデータをPOSTすることを目標としたいと思います。

インテグレーションを作成する

まずはインテグレーションを作成してみましょう。
以下のリンクから作成ができます。

ログインしたら、まず「新しいインテグレーション」をクリックしてください。

そしたらインテグレーションの概要入力欄が出てきます。

基本自由で構いませんが、ワークスペースが先ほど作成したテスト用のページがある場所かどうかを確認しておいてください。
作成出来たら、以下のような設定画面が開けます。

「内部インテグレーションシークレット」とありますね。
これがこのインテグレーションのトークンになります。

これは使うので、「表示」から「コピー」を選択してどこかにメモしておいてください。

ページにインテグレーションを追加する

さて、インテグレーションが作成できました。
次は、テスト用のページにインテグレーションを追加していきます。

Notion APIはどのページでも手放しでアクセスできるわけではなく、インテグレーションが追加されたページのみに対してアクセスができます。
そのため、インテグレーションができても、追加しないとAPIが叩けないんですね。

さて、インテグレーションを追加します。
テスト用のページを開き、右上の三点リーダーをクリック。
表示したメニューの中から「Add connections」を選択します。

その中にある、先ほど作成したインテグレーションをクリックして追加してください。
追加出来たら、以下のようにメニューの下に表示されます。

これで下準備は終わり...と行きたいですが、もう少しだけ準備が必要です。

アクセスしたいDBのIDを確認する

Notionでは、すべてのページ/DB/ブロックに対して一意なIDが割り振られています。そして、APIでアクセスする対象を指定するためには、そのIDが必要です。
今回はDBにアクセスしたいので、このDBのIDを知る必要があります。

方法ですが、まずはDBの共有リンクを生成します。
DBの三点メニューから「Copy link to view」をクリック。

そしたら、以下のような形式のURLが取得できます。

https://www.notion.so/<データベースID>?v=<ビューID>

このURLから「データベースID」の部分だけ抜き取ってメモしておきましょう。そしたら下準備はOK。

ここからは実際にAPIを叩いていくわけですが、僕はcURLとPostmanの二種類から試してみました。
Windowsの場合はデフォルトでcurlを使用できる環境ではない（Powershellにもcurlコマンドは存在しますが、文法が別物）なので、混乱を避けるためにもPostmanを使用することをお勧めします。
なお、WSL上ではcurlが動作するので、こちらを導入している場合はcurlでも構いません。

cURLを使う

cURL（カールとよみます）は、コマンドラインから様々なプロトコルでデータを転送できるコマンドツールです。よくライブラリをインストールしたりAPIテストでデータを送信したりするときに使いますね。

さて、curlからNotionにリクエストを送るときは、以下の公式ドキュメントから行いたい操作を探します。

例えば、データベースにデータをポストするためのリファレンスはここ。

サンプルコードから説明まで（英語ですが）丁寧に書いてあるので、基本的にここを読めば迷いません。

さて、実際にAPIを叩いてみましょう。
ここに、テストデータを挿入するためのcurlコマンドを書いてみました。

curl 'https://api.notion.com/v1/pages' \
  -H 'Authorization: Bearer ここにAPIトークン' \
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2022-06-28" \
  --data '{
	"parent": { "database_id": "ここにデータベースID" },
  "icon": {
  	"emoji": "🍀"
  },
 "properties": {
    "Name": {
      "title": [
        {
          "text": {
            "content": "Hello Integration！"
          }
        }
      ]
    }
  }
}'

APIトークン、およびデータベースIDは先ほどメモしたものに書き換えてください。
そしたら実行してみます。

おおー。
無事、コマンドからデータが生成されました。

Postmanを使う

Postmanとは、API開発をサポートするためのGUIツールです。Web上で使えるほか、Windowsならアプリをインストールしてローカルで動かすこともできます。

cURLでデバッグするのに比べ、同じ操作をキャッシュしたり、パラメータを視覚的にわかりやすく変更できたりするので、こちらのほうがデバッグには適している場合が多いです。

さて、同じようにDBにポストしてみましょう。
新しくリクエストを作成したとき、こんな感じの画面が表示されます。

まずはアクセス先のURLを設定しましょう。
ここではhttps://api.notion.com/v1/pagesとします。

そしたら設定をしていきます。
cURLでは引数にひとつひとつヘッダー情報などを書いていく必要がありましたが、Postmanでは各情報に応じたタブがあり、ここから情報を編集することができます。

ここでは2023/12/1に追加された日本語版での名称を使用しています。もしかしたら訳が変更されたりする場合があるので、その場合は公式ドキュメントなどを参照してください。

まずはAPIトークンを入力します。
「認証」タブを選択し、トークンタイプを「Bearer トークン」にしてからトークンをコピペしてください。

次に、NotionのAPIバージョンを指定します。
Notion APIの最新バージョンは以下より確認できます。

今回は2022-06-28です。

最後に、データの部分を入力していきます。
「ボディ」タブを選択し、データ形式に「Raw」を指定します。
入力するのはJsonなので、フォーマットは「JSON」にしてください。

最後に、HTTPメソッドをPOSTにします。

そして、送信ボタンを押すと...

おおー。
同じようにデータが送信されました。

余談：コレクションについて

今回は１からリクエストを作成してみましたが、実はこのPostmanにはコレクションという機能があります。
これは様々なリクエストをまとめたライブラリのようなもので、自分で作成したり、他人が作成したものを フォーク（コピー） したりできます。

実は、Notionは公式でPostmanのライブラリをサポートしており、フォークしていつでも参考にすることができます。↓

使うときは、上のリンクに飛び、三点メニューから「フォークを作成」を選択するだけ。

あとはざっくり概要を記入して、「コレクションをフォーク」を押します。

そしたら、自分のワークスペースにコピーされたコレクションができます。

コレクションのタブから「変数」をクリックすれば、コレクション内で共通の定数を設定することもできます。
ここにAPIトークンなどを設置すれば、複数リクエスト内で簡単に使いまわすことができますね。

おわりに

ちょうどWeb周りの学習でHTTPリクエストについて学んだので、この辺の話は結構面白かったです。
最近レガシーな環境ばかりで開発していて知識欲がうずうずしているので、次のハッカソンで採用してみようかしら。