notion-api

notion-api Best Practices

This guide establishes the definitive best practices for interacting with the Notion API. Adhering to these rules ensures our integrations are secure, performant, type-safe, and easily maintainable. We prioritize official SDKs and structured data handling.

1. Code Organization and Structure

Organize your Notion API interactions into dedicated modules. Separate concerns like authentication, data fetching, and data transformation.

✅ GOOD: Modular Structure

// src/notion/client.ts
import { Client } from '@notionhq/client';

export const notionClient = new Client({
  auth: process.env.NOTION_API_TOKEN,
});

// src/notion/pages.ts
import { notionClient } from './client';
import { CreatePageParameters, GetPageResponse } from '@notionhq/client/build/src/api-endpoints';

export async function createNotionPage(params: CreatePageParameters): Promise<GetPageResponse> {
  return notionClient.pages.create(params);
}

// src/notion/databases.ts
import { notionClient } from './client';
import { QueryDatabaseParameters, QueryDatabaseResponse } from '@notionhq/client/build/src/api-endpoints';

export async function queryNotionDatabase(databaseId: string, params?: QueryDatabaseParameters): Promise<QueryDatabaseResponse> {
  return notionClient.databases.query({ database_id: databaseId, ...params });
}

❌ BAD: Monolithic or Scattered Logic

// src/index.ts (or any random file)
import { Client } from '@notionhq/client';

async function main() {
  const notion = new Client({ auth: 'secret_token_hardcoded' }); // Hardcoded token is a major NO
  const response = await notion.databases.query({ database_id: 'some_id' });
  // ... page creation, block updates, all in one place
}

2. Authentication and Token Management

Always use granular integration tokens, store them in environment variables, and implement rotation. Never hardcode tokens.

✅ GOOD: Secure Token Handling

// .env
NOTION_API_TOKEN="secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

// src/notion/client.ts
import { Client } from '@notionhq/client';

if (!process.env.NOTION_API_TOKEN) {
  throw new Error('NOTION_API_TOKEN is not set in environment variables.');
}

export const notionClient = new Client({
  auth: process.env.NOTION_API_TOKEN,
});