バージョニング

Notion API はバージョン管理されています。API バージョンは、バージョンがリリースされた日付にちなんで名付けられています。たとえば、最新バージョンは2022-06-28です。

Notion-Versionヘッダーを含めてバージョンを設定します。

カールJavaScript

curl https://api.notion.com/v1/users/01da9b00-e400-4959-91ce-af55307647e5 \
  -H "Authorization: Bearer secret_t1CdN9S8yicG5eWLUOfhcWaOscVnFXns"
  -H "Notion-Version: 2022-06-28"

API に下位互換性のない変更を導入すると、新しい API バージョンがリリースされます。たとえば、プロパティ タイプの名前を変更します。

JSON

// Prior to version 2021-05-13, the rich text property is called "text"
"properties": {
    "Description": {
    "type": "text"
        "text": [ ... ]
    }
}

// In version 2021-05-13, the rich text property is now called "rich_text"
"properties": {
    "Description": {
    "type": "rich_text"
        "rich_text": [ ... ]
    }
}

上記の例では、新しいバージョンにアップグレードしない場合、ページの作成または更新時にtext を使用してテキスト プロパティを設定し続けます。新しいバージョンにアップグレードしたら、 rich_textを使用して同じテキスト プロパティを設定する必要があります。

同様に、古いバージョンではプロパティ タイプのページtext レスポンスが返されますが、新しいバージョンではrich_textになります。

🚧必須ヘッダー

すべてのリクエストにNotion-Versionヘッダーを含めることを強くお勧めします。これにより、Notion API がコードが期待するものと一致することが保証されます。2021 年 6 月 1 日以降、すべての API 呼び出しにNotion-Versionヘッダーを含める必要があります。

📘バージョニングは、後方互換性のない変更のみを対象としています

新しい API エンドポイントの追加や、既存の API エンドポイントの応答への新しいオブジェクトの追加など、API への新機能や追加については、新しいバージョンはありません。現在使用している API のバージョンで新しい機能を利用できます。

注: Notion API の URL に v1 が含まれていることにお気づきでしょうか。これは、上記のバージョンアップとは関係ありません。これらの URL を変更するつもりはありません。