Tinkering with the Notion API
We’re big fans of Notion at Orbit, using it for things as varied as product roadmap, onboarding documentation, Architecture Decision Records, and user interview notes. Its versatility is its biggest strength: we love its ability to adapt gracefully from a place to jot down notes to one that houses complex, interwoven knowledge databases.
For a long time, though, Notion was missing a key ingredient to truly become the central tool to a lot of teams, including ours: an API. In late January 2021, I got access to their private beta and started playing around with the many possibilities that it opened.
I got excited about building all kinds of fun projects with the API docs, but I quickly realized that I kept copy-pasting code from one to the other: calling endpoints, error handling, pagination. Suddenly, I had an itch to scratch, and I started working on an open-source Ruby client for the Notion API,
Releasing version 1.0
notion-ruby-client abstracts away the Notion API intricacies so that you can focus on building your own integration:
- All Notion API endpoints are available and documented;
- First-party support for pagination, rate-limiting, and API errors;
- Super simple configuration—you only need a single line of code to start using the API client
Getting started is as simple as this:
client = Notion::Client.new(token: '<your Notion API token>')
# Retrieving the title of a page # page = client.page(page_id: "c2a078405abf45bcb11c09fef6dfc3af") page.properties.Name.title.first.text.content # "🥬 Tuscan Kale" # Retrieving the contents of the first block of a page # blocks = client.block_children(block_id: "c2a078405abf45bcb11c09fef6dfc3af") blocks.results.first.paragraph.rich_text.first.text.content # "Lacinato 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."
What can it be used for?
At Orbit, we’ve built a number of projects, big and small, using notion-ruby-client:
community-ruby-notion-orbitis an Open Source Orbit integration, that synchronizes user interview notes taken in Notion to the community member’s profile in Orbit
- Station is our internal tool designed for sharing knowledge and building culture, which uses Notion as a CMS
notion-ruby-client also powers amazing open-source projects:
- Notion Tracker Create, using Notion to create an Atomic Habit-style tracker (@jimgraham)
- Bookworm, to import Kindle highlights into a Notion database (@zorbash)
- jekyll-notion, to import Notion pages into a Jekyll-powered website (@emoriarty)
The Notion API enables endless possibilities, ranging from personal workflows to powerful integrations with other services—I hope that
notion-ruby-client makes it easier to get started building your very own!
Originally published on the Orbit Blog.