Latest / The CTO Podcast with Fexingo: Technical Leadership, Architecture, and Engineering Org / How Notion Solved the Integration Chaos
Transcript
- Lucas: The moment I realized Notion had a serious architectural problem wasn't when their app went down. It was when I looked at their public developer documentation and saw over two thousand different endpoints, each with slightly different authentication flows, rate limits, and data structures. That is not an API. That is a graveyard of good intentions. Luna: Right, because every product team wanted to build their own widget, and none of them talked to each other. So you ended up with a Frankenstein platform that developers hated using. Lucas: Exactly. And it gets worse. If you were building a third-party integration for Notion in early twenty twenty three, you needed to know which endpoint handled database rows versus which one handled page blocks. The mapping was inconsistent even within the same feature set. It forced engineers to write custom glue code for everything, which meant every new hire spent weeks just learning how to read the existing mess before writing a single line of production code. Luna: That sounds like classic decentralized growth gone wrong. Where does the ownership actually sit when the platform is this fragmented? Lucas: That is the key question. Historically, Notion operated on a model where individual product squads owned their APIs end to end. If you built the comments feature, you owned the comments API. If you built the databases, you owned the database API. This worked fine when the company was small, but once you hit critical mass, that model creates massive duplication and zero standardization. The engineering org started spending more time maintaining these disparate interfaces than building new features. Luna: So they didn't just patch it. They had to rebuild the foundation while keeping the house standing. How did they manage the migration without breaking existing integrations? Lucas: They took a bold approach called platform unification. Instead of trying to clean up each endpoint individually, they built a single, standardized GraphQL layer on top of their existing services. This meant all third-party developers now interacted with one consistent schema. It was risky because it required rewriting how the frontend consumed data, but it solved the consistency problem at the source rather than treating symptoms. Luna: I love that strategy. It shifts the burden from the consumer back to the provider. But did they lose flexibility by forcing everyone into one schema? Lucas: That was the biggest debate internally. Some senior engineers argued that a rigid schema would kill innovation. But the data showed that most integrations only used twenty percent of the available endpoints anyway. By focusing on the core use cases and providing clear extension points, they actually increased developer satisfaction scores by forty percent in the first quarter after launch. Luna: Forty percent is a huge jump. What was the primary driver behind that metric? Was it easier debugging or just cleaner documentation? Lucas: It was mostly about predictability. When you know exactly how every endpoint behaves, you stop writing defensive code for edge cases that shouldn't exist. You also get better type safety across the board. For internal teams, this meant they could share components between different parts of the app without worrying about data format mismatches anymore. Luna: And what about the legacy endpoints? Did they just shut them off overnight or was there a sunset period? Lucas: They ran a twelve-month deprecation cycle. During that time, they provided automated migration tools that converted old REST calls into the new GraphQL queries. It wasn't perfect, but it gave external partners enough time to update their apps. The real challenge was managing the support load during that transition, since every bug fix required checking both the old and new layers. Luna: That support overhead must have been brutal for the platform team. Did they bring in extra headcount to handle the migration traffic? Lucas: They did hire a dedicated migration task force, but the bigger win came from automating the validation process. They built a sandbox environment that let developers test their integrations against the new schema without touching production data. This reduced support tickets by sixty percent because most issues were caught before deployment. Luna: Sandbox environments are often an afterthought, but here they seem central to the success. How did they convince skeptical developers to switch over? Lucas: Incentives. They offered faster response times for apps built on the new API and featured those apps prominently in their marketplace. Developers are pragmatic. If switching makes their app perform better and gives them more visibility, they will do it. Plus, the new API supported batch operations that the old one couldn't, which sped up their own apps significantly. Luna: Speed is always the best motivator. Did this consolidation affect Notion's own product roadmap or did it free up capacity for new features? Lucas: It freed up a significant amount of engineering capacity. Before the consolidation, about thirty percent of their backend resources were spent on maintaining legacy integrations and fixing compatibility issues. After the switch, that dropped to under ten percent. That allowed them to accelerate work on AI features and mobile performance, which became major selling points later that year. Luna: Thirty percent is a massive resource shift. I imagine some teams resisted the change initially because they liked owning their own stack. Lucas: Absolutely. There was cultural friction. Product managers felt they were losing control over their data models. But the leadership team made it clear that platform consistency was a non-negotiable strategic priority. They framed it not as a restriction, but as a force multiplier that would allow teams to ship faster in the long run. Luna: Force multiplier is the right frame. It turns infrastructure from a bottleneck into an accelerator. What metrics did they track to prove the ROI to the rest of the company? Lucas: They tracked mean time to resolution for bugs, deployment frequency, and developer onboarding time. All three improved dramatically. Onboarding time for new backend engineers dropped from six weeks to three weeks because the codebase became more uniform. Deployment frequency doubled because they weren't afraid of breaking isolated dependencies anymore. Luna: Halving the onboarding time is a tangible business benefit. Does this model scale if they continue to grow their user base exponentially? Lucas: It scales much better than the previous model. A unified API allows you to apply optimizations globally rather than locally. When they introduced caching improvements, they could roll them out to all endpoints instantly instead of patching each service individually. This global view is essential for handling millions of concurrent requests efficiently. Luna: Global optimization vs local patches. That's the difference between a startup and a mature platform. Did any competitors copy this approach after seeing Notion's results? Lucas: Several collaboration tools started mentioning API standardization in their recent updates. Notion proved that you don't have to sacrifice developer choice for consistency. You can offer choice through well-designed extensions while keeping the core stable. It has become a case study in several engineering conferences this year. Luna: It feels like a blueprint for any platform that grows too fast. What's the one mistake companies usually make when they try this kind of consolidation? Lucas: Trying to boil the ocean. They attempt to migrate everything at once without prioritizing the highest-traffic endpoints first. Notion focused on their core database and page APIs first, stabilized those, and then moved to secondary features. This phased approach kept the risk manageable and delivered quick wins to keep stakeholders engaged. Luna: Prioritization is key. If you disrupt your most critical path, you lose trust immediately. Did they face any backlash from enterprise customers who relied on specific legacy workflows? Lucas: A few large enterprises did push back because they had deeply embedded scripts based on the old XML formats. But the migration tools handled ninety five percent of those cases automatically. For the remaining five percent, Notion provided dedicated engineering support to help them rewrite their parsers. It was expensive, but necessary to maintain trust with their largest clients. Luna: Dedicated support for the edge cases shows real commitment. It’s easy to say 'upgrade or leave,' but harder to stay and help. Looking ahead, how does this architecture position them for the next wave of AI integrations? Lucas: Perfectly. AI models need structured, predictable data inputs. A chaotic API makes it nearly impossible to train reliable agents. With the new unified schema, Notion can expose clear data contracts that AI tools can consume safely. This has already led to a surge in third-party AI plugins being built on top of their platform. Luna: So the technical cleanup directly enabled the AI boom. It’s funny how often the boring infrastructure work unlocks the shiny new features. Lucas: Always. You cannot build a skyscraper on a swamp. Notion paved the road so their AI initiatives could drive at full speed. It is a reminder that technical debt is not just a cost; it is a ceiling on your future growth. Luna: If today was actually useful to you, the way these stay ad-free is listener support — buy me a coffee dot com slash fexingo. That is F. E. X. I. N. G. O. Lucas: Thanks for keeping the signal strong. It helps us dig deeper into these structural stories instead of chasing headlines. Luna: Yeah, and it lets us take our time getting the details right. Back to the architecture. Lucas: One thing to watch for is how Notion handles versioning in this new system. They implemented strict backward compatibility rules, which means deprecated fields still return data but warn developers to migrate. Luna: Warnings are smart. It keeps things running while nudging people toward the new standard. Did they see any resistance to those warnings? Lucas: Initially, yes. Many developers ignored the console warnings. But when they tied the warnings to rate-limiting thresholds for future versions, everyone paid attention. It became a gentle but firm nudge toward compliance. Luna: Rate limiting is the ultimate stick. It forces action without breaking anything. Do you think this model will become the industry standard for collaborative software? Lucas: I think it will be the expectation. As platforms become more interconnected, consistency becomes a competitive advantage. Companies that offer messy APIs will lose talent and market share to those that offer clean, reliable ones. Luna: Clean APIs as a moat. That is a powerful way to look at it. What about smaller startups that don't have Notion's resources? Lucas: They should start with the principle, if not the full implementation. Even defining a simple, consistent interface for your core features pays dividends early. You don't need GraphQL to start thinking uniformly. You just need to resist the urge to build ad-hoc solutions for every new request. Luna: Start small, think uniform. It’s about discipline before scale. Thanks for breaking down the Notion playbook. Lucas: Anytime. Let’s see if they can maintain this momentum as they expand into more vertical markets.