Introduction
I tried to use Notion API, so I would like to summarize it as a simple memorandum.
Contents of this article
- What is Notion
- What can you do with the Notion API?
- Try to touch the Notion API anyway!
What is Notion?
Are you using Notion?
I use it well for my side business and personal plan.
Personally, I keep a memo of my usual technical matters.
It's really good tools, I think.
Notion is a document management SaaS founded in 2013.
What is Notion?
The reason I use it is because it is "easy to use".
You can use it like a memo pad, but you can also easily create tables, ToDO lists, and project boards like Github in an instant.
I have the impression that it is widely used not only by engineers but also by people in the business domain because of its ease of use, which makes it easy to create documents.
Notion is growing steadily, reaching a valuation of $10 billion last year.
What can you do with the Notion API?
Notion released a public API on 2022/8/1.
I thought it might be possible to further improve work efficiency by using this, so I tried it.
Given the information in the reference above, let's summarize what you can do with each Notion component:
Notion Components
Notion has internal components. Specifically, there are "database", "table" and "block", and the simple relationship between each is as follows.
database
The database is the largest component that makes up Notion.
As you will see below, pages are grouped together and managed. It can be managed in the form of a table or board.
The corresponding API of the database is as follows. It seems that there is no deletion in CRUD.
| operation | explanation |
|---|---|
| query | Search for information in the database based on filter criteria. Add it when you want a list of pages under the database. |
| ID search | Get information about a database whose ID is known. |
| create | Create a new database |
| update | Update information in an existing database (such as renaming). |
page
Pages are the centerpiece of documents in Notion. Create notes and articles on this page.
The corresponding API of the page is as follows. Pages' API does not have database-like queries.
| operation | explanation |
|---|---|
| ID Search | Get information about a page whose ID is known. |
| create | Create a new page. |
| update | Update information on an existing page (such as renaming). |
| Get page properties | Get property information from page ID. |
In addition, there is an item for page deletion in the reference, but it is stated that you should use the end point of the block, so it is skipped here.
block
Blocks are individual elements that make up a page. For example, if you create a table in a page, that table becomes one block.
The corresponding API of the page is as follows.
| operation | explanation |
|---|---|
| ID Search | Get information about a block with a known ID. |
| Get child element | If there is a child element in that block, get it based on the ID. |
| create | Create a new block. |
| update | Update information on an existing page (such as renaming). |
| delete | Remove blocks. |
So far, we have introduced the API for Notion's components. There are also "User" and "Search" endpoints.
user
The corresponding API for the user is as follows.
| operation | explanation |
|---|---|
| ID Search | Get information about a user whose ID is known. |
| List acquisition | Get the user list in the workspace. |
| get bot | Get the bot user associated with the API token. |
search
| operation | explanation |
|---|---|
| query | Search for information among all pages that allow access from the API. |
Try to touch the Notion API anyway!
Here's a summary of what you can do with the API. From here, I will explain specifically how to use the API.
Visit Notion's My integrations
Go to https://www.notion.so/my-integrations .
You should see a screen like the one below.
Select + New integration on the left.
Enter as shown in the image below to create an integration.
When the creation is completed successfully, the Secret will be displayed above, so make a note of it.
Allow the created integration to access the database
I created an integration, so I want to hit the API with this! ...but before that, you need to share the database so that it can be accessed via the API.
Open Notion and click share for the database you want to share
Invite the integration you just created.
Try out the API
Now that we've completed the creation, it's time to try out the API. This time I will try to check it with curl simply.
Start Terminal. Let's run the following command in the started terminal!
By the way, replace with the Secret you wrote down earlier.
curl 'https://api.notion.com/v1/databases' \
-H 'Authorization: Bearer '"secret_xxxxxxxxxxxxxxxxxx"'' \
-H 'Notion-Version: 2021-08-16'
I think that the result will be returned as follows if it can be obtained successfully.
{"object":"list","results":[{"object":"database","id":"xxxxxxxxxxxxxxxxxxx","cover":null,"icon":null,"created_time":"2022-01-26T22:41:00.000Z","last_edited_time":"2022-02-08T02:00:00.000Z","title":[{"type":"text","text":{"content":"ToDo","link":null},"annotations":{"bold":false,"italic":false,"strikethrough":false,"underline":false,"code":false,"color":"default"},"plain_text":"ToDo","href":null}],"properties":{"Status":{"id":"%3DrdM","name":"Status","type":"select","select":{"options":[{"id":"1","name":"Not started","color":"red"},{"id":"2","name":"In progress","color":"yellow"},{"id":"3","name":"Completed","color":"green"}]}},"Assign":{"id":"WbC%5D","name":"Assign","type":"people","people":{}},"Name":{"id":"title","name":"Name","type":"title","title":{}}},"parent":{"type":"workspace","workspace":true},"url":"https://www.notion.so/xxxxxxxxxxxxxxxxxx"}],"next_cursor":null,"has_more":false}
Thoughts
I touched the public beta API published by Notion this time.
Notion is a very interesting tool, and I think it's a tool that will definitely grow in the future (or rather, it's already popular). I have the impression that the Notion API is still limited in functionality, but I would like to keep an eye on it to catch up on information.
Also, I'm trying to create a library in Go to touch the Notion API.
I'm still a newbie to Go, but I'm currently developing it, so I hope to publish more articles in the future, including things I noticed here.
Top comments (2)
I was trying to create something with it yesterday very simple concept but could not find a way to retrieve all the pages in db.
There's a lot of room for growth as you said. Good write up.
I've also worked with the notion API and I can definitely agree with your final thoughts. One think to keep in mind is that the API is super slow as soon as you run some advanced filters.