The Maze Is the Product
Stripe’s API documentation is widely considered the best in the industry. Developers praise it, reference it, and occasionally cite it as a reason they chose Stripe over competitors. But Stripe’s excellence is the exception precisely because it runs against the prevailing incentive. For most tech companies, clean and legible APIs represent a threat, not an achievement. Complexity is a moat.
The conventional read is that bad APIs result from bad engineering, organizational dysfunction, or simple neglect. That reading is too charitable. In many cases, the friction is intentional, the obfuscation is maintained, and the barriers to portability are features rather than bugs. Understanding why requires looking past the engineering decisions to the business logic underneath them.
Lock-In Is the Real Product
The economic logic is straightforward. When a developer builds deeply against your API, they accumulate what engineers call integration debt. Every custom workaround, every undocumented quirk absorbed into production code, every proprietary data format that only your tools understand, all of it raises the cost of switching to a competitor. The more confusing your API, the more integration debt your customers accrue, and the harder it becomes to leave.
Salesforce has operated this playbook for decades. Its API surface is vast, inconsistently documented, and littered with legacy endpoints that exist in parallel with newer ones doing roughly the same thing. Enterprise customers don’t complain publicly because their developers have long since mapped the terrain. But that mapping took months of institutional knowledge to build, and nobody wants to start over with a competitor. The complexity itself becomes the switching cost.
This isn’t unique to enterprise software. Twitter’s API restrictions, particularly the aggressive pricing changes rolled out in 2023 that killed hundreds of third-party clients and research tools overnight, demonstrated how API access can be weaponized to control which integrations survive. The developers who had built on the assumption of stable access were caught with technical debt and no good options. That’s not an accident of policy. That’s the policy.
The Hiring Signal Hidden in the Docs
There’s a secondary effect that rarely gets discussed. Deliberately complex APIs create demand for specialists who understand them, and those specialists tend to cluster inside the company that built them. When AWS launches a service with documentation that requires reading four other documents before the first one makes sense, it’s partly creating work for AWS consultants and AWS-certified professionals whose entire market value depends on that complexity persisting.
The AWS certification program, which now covers more than a dozen specialty tracks, exists because AWS’s services are difficult enough to warrant professional credentials. AWS benefits from that certification market directly through exam fees, but more importantly, it benefits indirectly. Every company that hires an AWS-certified architect is also buying deeper commitment to the AWS stack. You don’t pay to certify your team on a platform you’re planning to abandon.
This dynamic connects to something broader about how tech companies deliberately hide their best features: the value that’s easiest to find is rarely the value designed to retain you.
Complexity as Competitive Filter
Not all API friction serves retention. Some of it serves exclusion, specifically filtering out the customers you don’t want.
Consider the pattern around data portability. Under the EU’s GDPR and various state-level equivalents, companies are required to provide data export functionality. Many do. What they don’t have to do is make that export useful. Data dumps in nonstandard formats, missing relational context, or requiring technical interpretation to reconstruct original objects are all technically compliant. They’re also practically useless for anyone trying to migrate. The API exists. The friction is structural.
For enterprise platforms selling to large organizations, complexity also functions as a price filter. If your API requires six months of integration work before it delivers value, you’ve automatically excluded customers without the engineering resources to manage that. This suits vendors who want enterprise contracts and don’t want to field support requests from small businesses who can’t afford proper implementation teams. The friction is doing qualification work that sales teams don’t have to do explicitly.
When Good APIs Become Dangerous
The Stripe case is instructive because it shows what’s at stake when a company bets the other direction. Stripe’s developer-first philosophy, built on the insight that happy developers are the fastest sales channel in software, required genuine investment in API clarity. Stripe’s original seven-line integration was a deliberate act of product design, not a lucky accident. Patrick Collison has described the company’s obsession with reducing the number of steps required to accept a payment as a core strategic choice.
The bet paid off because developer goodwill is real and compounds. But it only works when network effects are weaker than reputation effects. Stripe succeeded partly because the payment processing market was fragmented and painful enough that a genuinely better API could win on merit. In markets where an incumbent already owns distribution, the calculus reverses. A competitor with a cleaner API can’t overcome the switching costs baked into an existing integration, no matter how elegant their documentation.
This is why the moat-through-complexity strategy works best after a platform achieves dominance. In the early stages, usability matters enormously. Once you have sufficient market share and your APIs are embedded in enough production systems, the incentive to maintain that software becomes much weaker, because the customers aren’t leaving anyway.
What Developers Should Actually Do
The practical implication for any developer or engineering team evaluating a new platform is this: assess not just the current API quality, but the incentives that will govern it five years from now. A startup with a clean API and no market power has every reason to keep improving the developer experience. A dominant platform with millions of integrations in production has every reason to let it stagnate.
Good documentation is a signal, but only at the margin. The more reliable signal is what happens to the API after the company stops needing your adoption and starts needing your retention. Watch what they do to the pricing structure. Watch whether breaking changes come with genuine migration support or a three-month deprecation notice buried in a changelog. Watch how much of the interesting functionality requires proprietary tooling rather than standard calls.
The maze tells you who built it and why. The question is whether you see it before you’re too far in to turn back.
