Coming here from Google? Sorry, this isn't about the Notion API — the Google Juice is just strong for this page. Instead, this is for Review Board, our open source code and document review product that's compatible with all major types of repositories and code hosting services. Learn more.

API v2 has served us well in Review Board, but we've hit limitations as it's grown, largely due to the depth of organization in the API, and partly due to evolving standards in the API.

There are a number of problems with the current API:

• The resource tree has a lot of resources that behave very similarly but differ in small ways (drafts vs. non-drafts, different levels of accessibility, etc.).
• The depth of resources make some queries impossible ("Give me all comments made by my user across all reviews made this month.")
• Sometimes we use fields for URLs, sometimes links.
• Some URLs are relative, not absolute.
• We have no mechanism for handling versioning of resources.
• It's easy to have name collisions in the API.

API v3 should be made to address these concerns. These design notes will cover how we intend to tackle these tasks.

This work is targeting Review Board 4.0.

Flatter Hierarchy

One of the key improvements we can make to the API is flattening up the hierarchy and making better use of queries to find what we need.