Notion Hello World

Overview

Minimal working example demonstrating core Notion functionality.

Prerequisites

• Completed notion-install-auth setup
• Valid API credentials configured
• Development environment ready

Instructions

Step 1: Create Entry File

Create a new file for your hello world example.

Step 2: Import and Initialize Client

import { NotionClient } from '@notion/sdk';

const client = new NotionClient({
  apiKey: process.env.NOTION_API_KEY,
});

Step 3: Make Your First API Call

async function main() {
  // Your first API call here
}

main().catch(console.error);

Output

• Working code file with Notion client initialization
• Successful API response confirming connection
• Console output showing:

Success! Your Notion connection is working.

Error Handling

Examples

TypeScript Example

import { NotionClient } from '@notion/sdk';

const client = new NotionClient({
  apiKey: process.env.NOTION_API_KEY,
});

async function main() {
  // Your first API call here
}

main().catch(console.error);

Python Example

from notion import NotionClient

client = NotionClient()

# Your first API call here

Resources

• Notion Getting Started
• Notion API Reference
• Notion Examples

Next Steps

Proceed to notion-local-dev-loop for development workflow setup.

Notion Incident Runbook

Overview

Rapid incident response procedures for Notion-related outages.

Prerequisites

• Access to Notion dashboard and status page
• kubectl access to production cluster
• Prometheus/Grafana access
• Communication channels (Slack, PagerDuty)

Severity Levels

Quick Triage

# 1. Check Notion status
curl -s https://status.notion.com | jq

# 2. Check our integration health
curl -s https://api.yourapp.com/health | jq '.services.notion'

# 3. Check error rate (last 5 min)
curl -s localhost:9090/api/v1/query?query=rate(notion_errors_total[5m])

# 4. Recent error logs
kubectl logs -l app=notion-integration --since=5m | grep -i error | tail -20

Decision Tree

Notion API returning errors?
├─ YES: Is status.notion.com showing incident?
│   ├─ YES → Wait for Notion to resolve. Enable fallback.
│   └─ NO → Our integration issue. Check credentials, config.
└─ NO: Is our service healthy?
    ├─ YES → Likely resolved or intermittent. Monitor.
    └─ NO → Our infrastructure issue. Check pods, memory, network.

Immediate Actions by Error Type

401/403 - Authentication

# Verify API key is set
kubectl get secret notion-secrets -o jsonpath='{.data.api-key}' | base64 -d

# Check if key was rotated
# → Verify in Notion dashboard

# Remediation: Update secret and restart pods
kubectl create secret generic notion-secrets --from-literal=api-key=NEW_KEY --dry-run=client -o yaml | kubectl apply -f -
kubectl rollout restart deployment/notion-integration

429 - Rate Limited

# Check rate limit headers
curl -v https://api.notion.com 2>&1 | grep -i rate

# Enable request queuing
kubectl set env deployment/notion-integration RATE_LIMIT_MODE=queue

# Long-term: Contact Notion for limit increase

500/503 - Notion Errors

# Enable graceful degradation
kubectl set env deployment/notion-integration NOTION_FALLBACK=true

# Notify users of degraded service
# Update status page

# Monitor Notion status for resolution

Communication Templates

Internal (Slack)

🔴 P1 INCIDENT: Notion Integration
Status: INVESTIGATING
Impact: [Describe user impact]
Current actio

Notion Known Pitfalls

Overview

Common mistakes and anti-patterns when integrating with Notion.

Prerequisites

• Access to Notion codebase for review
• Understanding of async/await patterns
• Knowledge of security best practices
• Familiarity with rate limiting concepts

Pitfall #1: Synchronous API Calls in Request Path

❌ Anti-Pattern

// User waits for Notion API call
app.post('/checkout', async (req, res) => {
  const payment = await notionClient.processPayment(req.body);  // 2-5s latency
  const notification = await notionClient.sendEmail(payment);   // Another 1-2s
  res.json({ success: true });  // User waited 3-7s
});

✅ Better Approach

// Return immediately, process async
app.post('/checkout', async (req, res) => {
  const jobId = await queue.enqueue('process-checkout', req.body);
  res.json({ jobId, status: 'processing' });  // 50ms response
});

// Background job
async function processCheckout(data) {
  const payment = await notionClient.processPayment(data);
  await notionClient.sendEmail(payment);
}

Pitfall #2: Not Handling Rate Limits

❌ Anti-Pattern

// Blast requests, crash on 429
for (const item of items) {
  await notionClient.process(item);  // Will hit rate limit
}

✅ Better Approach

import pLimit from 'p-limit';

const limit = pLimit(5);  // Max 5 concurrent
const rateLimiter = new RateLimiter({ tokensPerSecond: 10 });

for (const item of items) {
  await rateLimiter.acquire();
  await limit(() => notionClient.process(item));
}

Pitfall #3: Leaking API Keys

❌ Anti-Pattern

// In frontend code (visible to users!)
const client = new NotionClient({
  apiKey: 'sk_live_ACTUAL_KEY_HERE',  // Anyone can see this
});

// In git history
git commit -m "add API key"  // Exposed forever

✅ Better Approach

// Backend only, environment variable
const client = new NotionClient({
  apiKey: process.env.NOTION_API_KEY,
});

// Use .gitignore
.env
.env.local
.env.*.local

Pitfall #4: Ignoring Idempotency

❌ Anti-Pattern

// Network error on response = duplicate charge!
try {
  await notionClient.charge(order);
} catch (error) {
  if (error.code === 'NETWORK_ERROR') {
    await notionClient.charge(order);  // Charged twice!
  }
}

✅ Better Approach

const idempotencyKey = `order-${order.id}-${Date.now()}`;

await notionClient.charge(order, {
  idempotencyKey,  // Safe to retry
});

Pitfall #5: Not Validat

Notion Load & Scale

Overview

Load testing, scaling strategies, and capacity planning for Notion integrations.

Prerequisites

• k6 load testing tool installed
• Kubernetes cluster with HPA configured
• Prometheus for metrics collection
• Test environment API keys

Load Testing with k6

Basic Load Test

// notion-load-test.js
import http from 'k6/http';
import { check, sleep } from 'k6';

export const options = {
  stages: [
    { duration: '2m', target: 10 },   // Ramp up
    { duration: '5m', target: 10 },   // Steady state
    { duration: '2m', target: 50 },   // Ramp to peak
    { duration: '5m', target: 50 },   // Stress test
    { duration: '2m', target: 0 },    // Ramp down
  ],
  thresholds: {
    http_req_duration: ['p(95)<500'],
    http_req_failed: ['rate<0.01'],
  },
};

export default function () {
  const response = http.post(
    'https://api.notion.com/v1/resource',
    JSON.stringify({ test: true }),
    {
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${__ENV.NOTION_API_KEY}`,
      },
    }
  );

  check(response, {
    'status is 200': (r) => r.status === 200,
    'latency < 500ms': (r) => r.timings.duration < 500,
  });

  sleep(1);
}

Run Load Test

# Install k6
brew install k6  # macOS
# or: sudo apt install k6  # Linux

# Run test
k6 run --env NOTION_API_KEY=${NOTION_API_KEY} notion-load-test.js

# Run with output to InfluxDB
k6 run --out influxdb=http://localhost:8086/k6 notion-load-test.js

Scaling Patterns

Horizontal Scaling

# kubernetes HPA
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: notion-integration-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: notion-integration
  minReplicas: 2
  maxReplicas: 20
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70
    - type: Pods
      pods:
        metric:
          name: notion_queue_depth
        target:
          type: AverageValue
          averageValue: 100

Connection Pooling

import { Pool } from 'generic-pool';

const notionPool = Pool.create({
  create: async () => {
    return new NotionClient({
      apiKey: process.env.NOTION_API_KEY!,
    });
  },
  destroy: async (client) => {
    await client.close();
  },
  max: 20,
  min: 5,
  idleTimeoutMillis: 30000,
});

async function withNotionClient<T>(
  fn: (client: NotionClient) => Promise<T>
): Promise<T> {
  const client = await notionPool.acquire();
  try {
    retu

Notion Migration Deep Dive

Overview

Comprehensive guide for migrating to or from Notion, or major version upgrades.

Prerequisites

• Current system documentation
• Notion SDK installed
• Feature flag infrastructure
• Rollback strategy tested

Migration Types

Pre-Migration Assessment

Step 1: Current State Analysis

# Document current implementation
find . -name "*.ts" -o -name "*.py" | xargs grep -l "notion" > notion-files.txt

# Count integration points
wc -l notion-files.txt

# Identify dependencies
npm list | grep notion
pip freeze | grep notion

Step 2: Data Inventory

interface MigrationInventory {
  dataTypes: string[];
  recordCounts: Record<string, number>;
  dependencies: string[];
  integrationPoints: string[];
  customizations: string[];
}

async function assessNotionMigration(): Promise<MigrationInventory> {
  return {
    dataTypes: await getDataTypes(),
    recordCounts: await getRecordCounts(),
    dependencies: await analyzeDependencies(),
    integrationPoints: await findIntegrationPoints(),
    customizations: await documentCustomizations(),
  };
}

Migration Strategy: Strangler Fig Pattern

Phase 1: Parallel Run
┌─────────────┐     ┌─────────────┐
│   Old       │     │   New       │
│   System    │ ──▶ │  Notion   │
│   (100%)    │     │   (0%)      │
└─────────────┘     └─────────────┘

Phase 2: Gradual Shift
┌─────────────┐     ┌─────────────┐
│   Old       │     │   New       │
│   (50%)     │ ──▶ │   (50%)     │
└─────────────┘     └─────────────┘

Phase 3: Complete
┌─────────────┐     ┌─────────────┐
│   Old       │     │   New       │
│   (0%)      │ ──▶ │   (100%)    │
└─────────────┘     └─────────────┘

Implementation Plan

Phase 1: Setup (Week 1-2)

# Install Notion SDK
npm install @notion/sdk

# Configure credentials
cp .env.example .env.notion
# Edit with new credentials

# Verify connectivity
node -e "require('@notion/sdk').ping()"

Phase 2: Adapter Layer (Week 3-4)

// src/adapters/notion.ts
interface ServiceAdapter {
  create(data: CreateInput): Promise<Resource>;
  read(id: string): Promise<Resource>;
  update(id: string, data: UpdateInput): Promise<Resource>;
  delete(id: strin