Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add 'Intro to Notion API' example #441

Merged
Merged
2 changes: 2 additions & 0 deletions examples/intro-to-notion-api/.env.example
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
NOTION_API_KEY=<your-notion-api-key>
NOTION_PAGE_ID=<notion-page-id>
97 changes: 97 additions & 0 deletions examples/intro-to-notion-api/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
# Introduction to using Notion's SDK for JavaScript

## Learn how to make Public API requests

Use this sample code to learn how to make Public API requests with varying degrees of difficulty.

The sample code is split into two sections:

1. `basic`
2. `intermediate`

(An `advanced` section will soon be added, as well.)

If you are new to Notion's SDK for JavaScript, start with the code samples in the `/basic` directory to get more familiar to basic concepts.

The files in each directory will build on each other to increase in complexity. For example, in `/intermediate`, first you will see how to create a database, then how to create a database and add a page to it, and finally create a database, add a page, and query/sort the database.

## Table of contents

In case you are looking for example code for a specific task, the files are divided as follows:

- `/basic/1-add-block.js`: Create a new block and append it to an existing Notion page.
- `/basic/2-add-linked-block.js`: Create and append new blocks, and add a link to the text of a new block.
- `/basic/3-add-styled-block.js`: Create and append new blocks, and apply text styles to them.
- `/intermediate/1-create-a-database.js`: Create a new database with defined properties.
- `/intermediate/2-add-page-to-database.js`: Create a new database and add new pages to it.
- `/intermediate/3-query-database.js`: Create a new database, add pages to it, and filter the database entries (pages).
- `/intermediate/4-sort-database.js`: Create a new database, add pages to it, and filter/sort the database entries (pages).

## Running locally

### 1. Clone project and install dependencies

To use this example on your machine, clone the repo and move into your local copy:

```zsh
git clone https://github.com/makenotion/notion-sdk-js.git
cd /notion-sdk-js
```

Next, move into this example in the `/examples` directory, and install its dependencies:

```zsh
cd /examples/intro-to-notion-api
npm install
```

### 2. Set your environment variables in a `.env` file

A `.env.example` file has been included and can be renamed `.env` (or you can run `cp .env.example .env` to copy the file).

Update the environment variables below:

```zsh
NOTION_API_KEY=<your-notion-api-key>
NOTION_PAGE_ID=<notion-page-id>
```

`NOTION_API_KEY`: Create a new integration in the [integrations dashboard](https://www.notion.com/my-integrations) and retrieve the API key from the integration's `Secrets` page.

`NOTION_PAGE_ID`: Use the ID of any Notion page that you want to test adding content to.

The page ID is the 32 character string at the end of any page URL.
![A Notion page URL with the ID highlighted](./assets/page_id.png)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this supposed to be an example Notion page URL?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it is!


### 3. Give the integration access to your page

Your Notion integration will need permission to interact with the Notion page being used for your `NOTION_PAGE_ID` variable. To provide access, do the following:

1. Go to the page in your workspace.
2. Click the `•••` (more menu) on the top-right corner of the page.
3. Scroll to the bottom of the menu and click `Add connections`.
4. Search for and select your integration in the `Search for connections...` menu.

Once selected, your integration will have permission to read content from the page.

**If you are receiving authorization errors, make sure the integration has permission to access the page.**

### 3. Run individual examples

To run each individual example, use the `node` command with the file's path.

For example:

```zsh
node /basic/1-add-block.js
```

---

## Additional resources

To learn more, read the [Public API docs](https://developers.notion.com/) for additional information on using Notion's API. The API docs include a series of [guides](https://developers.notion.com/docs) and the [API reference](https://developers.notion.com/reference/intro), which has a full list of available endpoints.

To see more examples of what you can build with Notion, see our other sample integrations in the parent `/examples` directory. To learn how to build an internal integration with an interactive frontend, read the [Build your first integration](https://developers.notion.com/docs/create-a-notion-integration) guide.

To connect with other developers building with Notion, join the [Notion Developers Slack group](https://join.slack.com/t/notiondevs/shared_invite/zt-20b5996xv-DzJdLiympy6jP0GGzu3AMg).
Binary file added examples/intro-to-notion-api/assets/page_id.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
45 changes: 45 additions & 0 deletions examples/intro-to-notion-api/basic/1-add-block.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
import { Client } from "@notionhq/client"
import { config } from "dotenv"

config()

const pageId = process.env.NOTION_PAGE_ID
const apiKey = process.env.NOTION_API_KEY

const notion = new Client({ auth: apiKey })

/*
---------------------------------------------------------------------------
*/

/**
* Resources:
* - Appending block children endpoint (notion.blocks.children.append(): https://developers.notion.com/reference/patch-block-children)
* - Working with page content guide: https://developers.notion.com/docs/working-with-page-content
*/

async function main() {
const blockId = pageId // Blocks can be appended to other blocks *or* pages. Therefore, a page ID can be used for the block_id parameter
const newHeadingResponse = await notion.blocks.children.append({
block_id: blockId,
// Pass an array of blocks to append to the page: https://developers.notion.com/reference/block#block-type-objects
children: [
{
heading_2: {
rich_text: [
{
text: {
content: "Types of kale", // This is the text that will be displayed in Notion
},
},
],
},
},
],
})

// Print the new block(s) response
console.log(newHeadingResponse)
}

main()
62 changes: 62 additions & 0 deletions examples/intro-to-notion-api/basic/2-add-linked-block.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
import { Client } from "@notionhq/client"
import { config } from "dotenv"

config()

const pageId = process.env.NOTION_PAGE_ID
const apiKey = process.env.NOTION_API_KEY

const notion = new Client({ auth: apiKey })

/*
---------------------------------------------------------------------------
*/

/**
* Resources:
* - Appending block children endpoint (notion.blocks.children.append(): https://developers.notion.com/reference/patch-block-children)
* - Rich text options: https://developers.notion.com/reference/rich-text
* - Working with page content guide: https://developers.notion.com/docs/working-with-page-content
*/

async function main() {
const blockId = pageId // Blocks can be appended to other blocks *or* pages. Therefore, a page ID can be used for the block_id parameter
const linkedTextResponse = await notion.blocks.children.append({
block_id: blockId,
// Pass an array of blocks to append to the page: https://developers.notion.com/reference/block#block-type-objects
children: [
{
heading_3: {
rich_text: [
{
text: {
content: "Tuscan kale", // This is the text that will be displayed in Notion
},
},
],
},
},
{
paragraph: {
rich_text: [
{
text: {
content:
"Tuscan kale is a variety of kale with a long tradition in Italian cuisine, especially that of Tuscany. It is also known as Tuscan kale, Italian kale, dinosaur kale, kale, flat back kale, palm tree kale, or black Tuscan palm.",
link: {
// Include a url to make the paragraph a link in Notion
url: "https://en.wikipedia.org/wiki/Kale",
},
},
},
],
},
},
],
})

// Print the new block(s) response
console.log(linkedTextResponse)
}

main()
70 changes: 70 additions & 0 deletions examples/intro-to-notion-api/basic/3-add-styled-block.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
import { Client } from "@notionhq/client"
import { config } from "dotenv"

config()

const pageId = process.env.NOTION_PAGE_ID
const apiKey = process.env.NOTION_API_KEY

const notion = new Client({ auth: apiKey })

/*
---------------------------------------------------------------------------
*/

/**
* Resources:
* - Appending block children endpoint (notion.blocks.children.append(): https://developers.notion.com/reference/patch-block-children)
* - Rich text options: https://developers.notion.com/reference/rich-text
* - Working with page content guide: https://developers.notion.com/docs/working-with-page-content
*/

async function main() {
const blockId = pageId // Blocks can be appended to other blocks *or* pages. Therefore, a page ID can be used for the block_id parameter
const styledLinkTextResponse = await notion.blocks.children.append({
block_id: blockId,
children: [
{
heading_3: {
rich_text: [
{
text: {
content: "Tuscan kale",
},
},
],
},
},
{
paragraph: {
rich_text: [
{
text: {
// Paragraph text
content:
"Tuscan kale is a variety of kale with a long tradition in Italian cuisine, especially that of Tuscany. It is also known as Tuscan kale, Italian kale, dinosaur kale, kale, flat back kale, palm tree kale, or black Tuscan palm.",
link: {
// Paragraph link
url: "https://en.wikipedia.org/wiki/Kale",
},
},
annotations: {
// Paragraph styles
bold: true,
italic: true,
strikethrough: true,
underline: true,
color: "green",
},
},
],
},
},
],
})

// Print the new block(s) response
console.log(styledLinkTextResponse)
}

main()
59 changes: 59 additions & 0 deletions examples/intro-to-notion-api/intermediate/1-create-a-database.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
import { Client } from "@notionhq/client"
import { config } from "dotenv"

config()

const pageId = process.env.NOTION_PAGE_ID
const apiKey = process.env.NOTION_API_KEY

const notion = new Client({ auth: apiKey })

/*
---------------------------------------------------------------------------
*/

/**
* Resources:
* - Create a database endpoint (notion.databases.create(): https://developers.notion.com/reference/create-a-database)
* - Working with databases guide: https://developers.notion.com/docs/working-with-databases
*/

async function main() {
// Create a new database
const newDatabase = await notion.databases.create({
parent: {
type: "page_id",
page_id: pageId,
},
title: [
{
type: "text",
text: {
content: "New database name",
},
},
],
properties: {
// These properties represent columns in the database (i.e. its schema)
"Grocery item": {
type: "title",
title: {},
},
Price: {
type: "number",
number: {
format: "dollar",
},
},
"Last ordered": {
type: "date",
date: {},
},
},
})

// Print the new database response
console.log(newDatabase)
}

main()
Loading
Loading