Step by Step Guide to Building a Notion API Integration in JS

Introduction

Hey there, fellow developer! Ready to dive into the world of Notion API integrations? You're in for a treat. We'll be using the @notionhq/client package to make our lives easier. Let's get cracking!

Prerequisites

Before we jump in, make sure you've got:

• Node.js installed (you're a dev, so I'm sure you do!)
• A Notion account (if you don't have one, what are you waiting for?)
• Some JavaScript chops (I know you've got 'em)

Setting up the Notion Integration

First things first, let's get you set up with Notion:

1. Head over to your Notion account and create a new integration.
2. Grab that shiny new API key – we'll need it soon!

Project Setup

Time to get our hands dirty:

mkdir notion-api-project
cd notion-api-project
npm init -y
npm install @notionhq/client

Easy peasy, right?

Connecting to the Notion API

Let's write some code:

const { Client } = require('@notionhq/client');

const notion = new Client({ auth: 'your-api-key-here' });

Boom! You're connected. Feel the power!

Basic Operations

Retrieving a Page

async function getPage(pageId) {
  const response = await notion.pages.retrieve({ page_id: pageId });
  console.log(response);
}

Creating a New Page

async function createPage(parentId, title) {
  const response = await notion.pages.create({
    parent: { database_id: parentId },
    properties: {
      title: {
        title: [{ text: { content: title } }]
      }
    }
  });
  console.log(response);
}

Updating a Page

async function updatePage(pageId, newTitle) {
  const response = await notion.pages.update({
    page_id: pageId,
    properties: {
      title: {
        title: [{ text: { content: newTitle } }]
      }
    }
  });
  console.log(response);
}

Deleting a Page

async function deletePage(pageId) {
  const response = await notion.pages.update({
    page_id: pageId,
    archived: true
  });
  console.log(response);
}

Working with Databases

Querying a Database

async function queryDatabase(databaseId) {
  const response = await notion.databases.query({
    database_id: databaseId
  });
  console.log(response);
}

Adding Items to a Database

async function addDatabaseItem(databaseId, title) {
  const response = await notion.pages.create({
    parent: { database_id: databaseId },
    properties: {
      Name: {
        title: [{ text: { content: title } }]
      }
    }
  });
  console.log(response);
}

Updating Database Items

async function updateDatabaseItem(pageId, newTitle) {
  const response = await notion.pages.update({
    page_id: pageId,
    properties: {
      Name: {
        title: [{ text: { content: newTitle } }]
      }
    }
  });
  console.log(response);
}

Advanced Features

Using Filters and Sorts in Queries

async function advancedQuery(databaseId) {
  const response = await notion.databases.query({
    database_id: databaseId,
    filter: {
      property: 'Status',
      select: {
        equals: 'Done'
      }
    },
    sorts: [
      {
        property: 'Date',
        direction: 'descending'
      }
    ]
  });
  console.log(response);
}

Working with Blocks

async function addBlock(pageId) {
  const response = await notion.blocks.children.append({
    block_id: pageId,
    children: [
      {
        object: 'block',
        type: 'paragraph',
        paragraph: {
          text: [{ type: 'text', text: { content: 'Hello, World!' } }]
        }
      }
    ]
  });
  console.log(response);
}

Error Handling and Best Practices

Always wrap your API calls in try-catch blocks:

try {
  await notion.pages.retrieve({ page_id: 'non-existent-id' });
} catch (error) {
  console.error(error.body);
}

And don't forget about rate limits! Be kind to the API:

const { promisify } = require('util');
const sleep = promisify(setTimeout);

async function rateLimitedOperation() {
  try {
    await notion.databases.query({ database_id: 'your-database-id' });
    await sleep(334); // Roughly 3 requests per second
  } catch (error) {
    if (error.code === 'rate_limited') {
      console.log('Rate limited! Waiting before retry...');
      await sleep(error.retryAfter * 1000);
    } else {
      throw error;
    }
  }
}

Conclusion

And there you have it! You're now equipped to build some awesome Notion integrations. Remember, this is just scratching the surface – there's so much more you can do with the Notion API. Keep exploring, keep building, and most importantly, have fun!

For more in-depth info, check out the official Notion API documentation. Now go forth and create something amazing!