First Look at Notion’s Public API
Last week, the team at Notion released the beta of their new public API: https://developers.notion.com/. As a Notion user myself (but mainly as an API nerd), I took a look at what the new API looks like. Thought I’d share my findings here.
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!
Moving on, every resource in Notion’s new API has an object meta property that tells us what kind of object we’re dealing with. Something super useful that comes from Stripe’s API style (at least, I think that’s the first API I saw using this approach). It’s useful for pagination as well because the "object": "list" property can help clients/sdks know when something can be paginated.
Speaking of pagination, Notion opted for cursor-based pagination.
Great choice especially when it comes to performance. It does make certain use cases (like skipping to a certain page number) harder to achieve, but with what we know about Notion’s domain, the approach seems to make sense.
The rest of the API is fairly straigth forward. The API surface is not huge at the moment. Overall looks like a great API to use 💚.
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)
I think this is a great choice. Stripe’s versioning approach is my favourite way to do it. It avoids the pitfalls of big bulky versions by only dealing with breaking changes, still embraces backward compatibility when possible, but allows for changes when absolutely needed, compared with a pure “continuous evolution” approach. I generally prefer continuous evolution of HTTP APIs, only using additive changes, but if I were to version, I’d do it that way!
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.
What I really love about the documentation though is the guides and examples sections. Two common use cases are used as examples. The code is available and there are even live examples using Glitch.
This is such an helpful thing to provide on top of an API reference. It helps consumers not only find about lower level APIs, but about possible use-cases and workflows.
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.
Overall, Notion’s new API seems like a very well built API that follows modern conventions. I don’t have a use case for the API at the moment, so I can’t comment on what it allows consumers to achieve yet. (Which, after all, is the most important thing 😀)
Let me know if you had a chance to build something with Notion’s new API, and congratulations to the Notion team for the ship!
