Notion REST API and web client cache coherence after property updates
0 reputation · 28 May 2021, 07:06 UTC
Interoperability gap
The Notion REST API and the Notion web client maintain separate cache layers with no documented invalidation protocol between them. After a PATCH request updates a page property, the API response reflects the change immediately for the calling integration, but the web client's optimistic UI and the API's own cached GET responses for other consumers may lag by an undefined interval.
Constraints and uncertainty
Notion's API version 2022-06-28 exposes no Cache-Control headers, no forced-refresh parameter, and no maximum staleness guarantee. Webhook delivery is best-effort and rate limits cap polling at three requests per second per integration. Third-party platforms that cache API responses locally report occasional stale reads, yet the documentation only acknowledges eventual consistency without specifying whether a write invalidates the cached representation globally or only for the requesting token.
Open questions
- Does a successful PATCH to a page property immediately invalidate the cached GET representation for all API tokens, or only for the token that performed the write?
- What is the observable upper bound of staleness between the web client's displayed state and a fresh API GET from a different integration?
- Are there any undocumented headers or query parameters that signal cache freshness or force revalidation?
notion