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

Introduction

Hey there, fellow developer! Ready to dive into the world of Notion API integration using Go? You're in for a treat. We'll be using the awesome dstotijn/go-notion package to make our lives easier. Buckle up, and let's get coding!

Prerequisites

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

• Go installed on your machine
• A Notion account and API key
• Some basic Go and Notion knowledge (but don't worry, we'll guide you through)

Setting up the project

Let's kick things off by creating a new Go module:

mkdir notion-integration && cd notion-integration
go mod init github.com/yourusername/notion-integration

Now, let's grab the dstotijn/go-notion package:

go get github.com/dstotijn/go-notion

Authenticating with Notion API

First things first, you'll need an API key. Head over to your Notion integrations page and create a new integration. Copy that API key, and let's use it to initialize our Notion client:

import (
    "github.com/dstotijn/go-notion"
)

client := notion.NewClient("your-api-key-here")

Basic operations

Retrieving a page

Let's fetch a page from Notion:

page, err := client.FindPageByID(context.Background(), "your-page-id")
if err != nil {
    log.Fatalf("Error retrieving page: %v", err)
}
fmt.Printf("Page title: %s\n", page.Properties["title"])

Creating a new page

Time to create a new page:

newPage, err := client.CreatePage(context.Background(), notion.CreatePageParams{
    ParentType: notion.ParentTypePageID,
    ParentID:   "parent-page-id",
    Title:      []notion.RichText{{Text: &notion.Text{Content: "My New Page"}}},
})

Updating page content

Updating is just as easy:

_, err = client.UpdatePage(context.Background(), "page-id", notion.UpdatePageParams{
    Properties: notion.Properties{
        "title": notion.TitleProperty{
            Title: []notion.RichText{{Text: &notion.Text{Content: "Updated Title"}}},
        },
    },
})

Working with databases

Querying a database

Let's fetch some data:

results, err := client.QueryDatabase(context.Background(), "database-id", &notion.DatabaseQuery{})
if err != nil {
    log.Fatalf("Error querying database: %v", err)
}
for _, page := range results.Results {
    fmt.Printf("Page title: %s\n", page.Properties["Name"].Title[0].PlainText)
}

Adding items to a database

Adding new items is a breeze:

_, err = client.CreatePage(context.Background(), notion.CreatePageParams{
    ParentType: notion.ParentTypeDatabaseID,
    ParentID:   "database-id",
    Properties: notion.Properties{
        "Name": notion.TitleProperty{
            Title: []notion.RichText{{Text: &notion.Text{Content: "New Item"}}},
        },
    },
})

Advanced features

Using blocks to structure content

Blocks are the building blocks of Notion pages:

blocks, err := client.AppendBlockChildren(context.Background(), "page-id", []notion.Block{
    notion.Heading1Block{
        RichText: []notion.RichText{{Text: &notion.Text{Content: "Hello, Notion!"}}},
    },
    notion.ParagraphBlock{
        RichText: []notion.RichText{{Text: &notion.Text{Content: "This is a paragraph."}}},
    },
})

Working with comments

Let's add a comment to a page:

comment, err := client.CreateComment(context.Background(), notion.CreateCommentParams{
    ParentPageID: "page-id",
    RichText: []notion.RichText{
        {Text: &notion.Text{Content: "Great work on this page!"}},
    },
})

Error handling and best practices

Always handle your errors gracefully and be mindful of rate limits. The go-notion package helps with retries, but it's good to add your own error handling:

if err != nil {
    if notion.IsNotionError(err) {
        notionErr := err.(*notion.Error)
        log.Printf("Notion API error: %s (code: %s)", notionErr.Message, notionErr.Code)
    } else {
        log.Printf("Unexpected error: %v", err)
    }
}

Testing and debugging

Don't forget to write tests for your integration! Here's a quick example:

func TestCreatePage(t *testing.T) {
    client := notion.NewClient("your-test-api-key")
    page, err := client.CreatePage(context.Background(), notion.CreatePageParams{
        // ... test parameters ...
    })
    if err != nil {
        t.Fatalf("Failed to create page: %v", err)
    }
    if page.ID == "" {
        t.Error("Expected page ID, got empty string")
    }
}

Conclusion

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

For more in-depth information, check out the Notion API documentation and the go-notion package documentation. Happy coding!