bot_vault

API Design and OOP: Narrow, Tight Interfaces Over Object Hierarchies

3 min read

Summary

A fintech engineer with 5+ years building production web APIs argues that the dominant OOP-style CRUD API design (Stripe’s model) is not universally correct — comparing it to Google Places’ non-object-oriented approach where clients specify which data fields they need. The core thesis: make APIs “narrow and tight” (minimal surface area, atomic data access) to minimize the blast radius of any single change.

一位金融科技工程師比較 Stripe（OOP 式 CRUD API）和 Google Places（原子欄位存取）的設計哲學，論證「窄而緊湊」的 API 才能在不破壞客戶端的情況下持續演進。核心原則：最小化公開介面，以降低每次更改的影響範圍。

Key Points

  • Narrow and tight: fewer publicly accessible operations = smaller contract = safer to change internals. Author’s fintech API ran 5+ years without a single public version bump
  • Atomic data access: instead of returning a Book object, return a list of ISBNs and expose atomic endpoints per attribute (GET /book/<isbn>/title, GET /book/<isbn>/author). Clients unaffected by changes to fields they don’t use
  • Stripe vs. Google Places: Stripe uses full object definitions (OOP, CRUD-oriented, works because they own all the data); Google Places doesn’t define a “Place” object formally and lets clients pick fields — appropriate when data is messy and owned externally
  • The /v2 problem: frequent API version bumps are often a design symptom, not a feature. Each version requires all clients to update their code
  • CRUD is not the whole picture: even Stripe, the exemplar of CRUD API design, includes a non-CRUD search operation — real-world APIs always escape the CRUD model

Insights

The “narrow and tight” principle generalizes beyond web APIs to any interface design: class APIs, CLI tools, library ABIs. The fewer things you expose, the fewer things you have to keep stable. This is exactly what information hiding / encapsulation is supposed to achieve, but it’s often lost in the rush to provide “complete” APIs.

The fintech example (5 years, no /v2) is rare enough to be instructive. The key was adding a boolean flag atomically rather than changing the existing response structure — the flag was transparent to clients who didn’t read it, visible to those who needed it. Additive changes are almost always backwards-compatible; structural changes almost never are.

The Google Places vs. Stripe comparison is a useful mental model: when you own the data (like Stripe owns payment data), OOP object definitions make sense. When you’re a layer over messy external data (like Places over physical world data), forcing object definitions creates false precision.

Connections

Raw Excerpt

Make your API narrow and tight. Users must walk a narrow path to get what they want. The impact of any change is minimal when the scope of the change is minimal — and the scope can be minimal if the algorithms and data structures that are publicly accessible are accessible nearly atomically.

Graph View

Backlinks