Step by Step Guide to Building a Notion API Integration in C#

Jul 17, 2024 • 8 minute read

Introduction

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

Prerequisites

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

.NET SDK installed
A Notion account (duh!)
Visual Studio or your IDE of choice

Setting up the Notion Integration

First things first, let's set up our Notion integration:

Head over to Notion's integrations page
Click "New integration" and give it a cool name
Grab that API key – we'll need it soon!

Installing Notion.Net

Time to add some firepower to our project. Open up your package manager console and run:

Install-Package Notion.Net

Easy peasy!

Initializing the Notion Client

Let's get that Notion client up and running:

using Notion.Client;

var client = NotionClientFactory.Create(new ClientOptions
{
    AuthToken = "your-secret-api-key"
});

Authentication

See that AuthToken we just used? That's all the authentication we need. Your API key is your golden ticket!

Basic Operations

Retrieving a Page

Want to fetch a page? Here's how:

var page = await client.Pages.RetrieveAsync("your-page-id");

Creating a New Page

Let's birth a new page into existence:

var newPage = await client.Pages.CreateAsync(new PagesCreateParameters
{
    Parent = new ParentPageInput { PageId = "parent-page-id" },
    Properties = new Dictionary<string, PropertyValue>
    {
        { "Name", new TitlePropertyValue { Title = new List<RichTextBase> { new RichTextText { Text = new Text { Content = "My Awesome Page" } } } } }
    }
});

Updating Page Properties

Time for a makeover:

await client.Pages.UpdateAsync("page-id", new PagesUpdateParameters
{
    Properties = new Dictionary<string, PropertyValue>
    {
        { "Name", new TitlePropertyValue { Title = new List<RichTextBase> { new RichTextText { Text = new Text { Content = "My Even More Awesome Page" } } } } }
    }
});

Deleting a Page

When it's time to say goodbye:

await client.Pages.UpdateAsync("page-id", new PagesUpdateParameters
{
    Archived = true
});

Working with Databases

Querying a Database

Let's fetch some data:

var queryParams = new DatabasesQueryParameters();
var results = await client.Databases.QueryAsync("database-id", queryParams);

Adding Items to a Database

Populating our database:

await client.Pages.CreateAsync(new PagesCreateParameters
{
    Parent = new ParentDatabaseInput { DatabaseId = "database-id" },
    Properties = new Dictionary<string, PropertyValue>
    {
        { "Name", new TitlePropertyValue { Title = new List<RichTextBase> { new RichTextText { Text = new Text { Content = "New Item" } } } } },
        { "Tags", new MultiSelectPropertyValue { MultiSelect = new List<SelectOption> { new SelectOption { Name = "Important" } } } }
    }
});

Updating Database Items

Keeping things fresh:

await client.Pages.UpdateAsync("page-id", new PagesUpdateParameters
{
    Properties = new Dictionary<string, PropertyValue>
    {
        { "Status", new SelectPropertyValue { Select = new SelectOption { Name = "Completed" } } }
    }
});

Advanced Features

Working with Blocks

Let's add some content:

await client.Blocks.AppendChildrenAsync("page-id", new BlocksAppendChildrenParameters
{
    Children = new List<IBlockObjectRequest>
    {
        new ParagraphBlockObjectRequest
        {
            Paragraph = new ParagraphBlock
            {
                RichText = new List<RichTextBase> { new RichTextText { Text = new Text { Content = "Hello, Notion!" } } }
            }
        }
    }
});

Handling Rich Text Content

Rich text, rich possibilities:

var richText = new List<RichTextBase>
{
    new RichTextText
    {
        Text = new Text { Content = "Bold and " },
        Annotations = new Annotations { Bold = true }
    },
    new RichTextText
    {
        Text = new Text { Content = "italic" },
        Annotations = new Annotations { Italic = true }
    }
};

Error Handling and Best Practices

Always wrap your API calls in try-catch blocks:

try
{
    // Your Notion API call here
}
catch (NotionApiException ex)
{
    Console.WriteLine($"Oops! {ex.Message}");
}

And remember, Notion has rate limits. Be nice to their servers!

Conclusion

And there you have it! You're now armed with the knowledge to build some seriously cool Notion integrations. The sky's the limit – go forth and create!

Resources

Now go make something awesome! 🚀