First Look at Notion’s Public API

API Style

Let’s start by the API style. Some would’ve like a GraphQL API, but the team chose to go with the paved path of a JSON HTTP API. REST fans might also be bummed out, as Notion’s new API does not make use of HTTP links between resources and/or handle state. Nothing wrong with a good old HTTP API without links, but I do think Notion’s domain would have been a particularly good fit for hypermedia. Something that can easily be added if needed. I would have liked to be a fly on the wall during the design of the API, I wonder if GraphQL was considered, and what trade-offs they considered there!

Cursor-based pagination (https://developers.notion.com/reference/pagination)

Versioning

Notion’s versioning is also something straight from Stripe’s book. We find the most important points of Stripe’s versioning strategy also present in Notion’s versioning:

  • Date-based versions.
  • Additive changes are added to all versions, only breaking changes require a new one.
  • Versions are selected through a header.
  • URL versioning is present, but only in the rare case where it’s needed. (A brand new API, very large change, etc)

Documentation

Notion seems to be using ReadMe for their documentation. Absolutely a great choice there too. The team is probably too small to roll their own documentation platform and ReadMe is great at what they do.

https://developers.notion.com/reference/get-database
https://developers.notion.com/page/examples

Auth

There are two ways to authenticate against Notion’s API at the moment. You can create an “internal” integration that is only to be used against your organization, or go with the typical OAuth app that would be able to integrate with any number of orgs. I love this, since the internal integration style lets you get started very quickly without having to do a full OAuth dance. Reminds me of GitHub’s personal tokens.

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Marc-André Giroux

Marc-André Giroux

#GraphQL Enthusiast, Speaker, Senior Software Developer @ Netflix 📖 Book is now available https://book.productionreadygraphql.com/