Spelunking our network of assumptionsseven days beforeI’ve noticed that my ability to operate in an ambiguous, complex environment…Polarity-based API layering

The Layering Principle2023Preference toward layering is probably one of the more fundamental principles of…While discussing API design, one pattern that caught my eye was polarity-based layering. It’s something that I’ve learned to do intuitively, but thought it might be worth capturing.

Shadows and Curses2022The second curse can be seen as the interplay between “ 🔮…The platform two-step2022When we last saw Uncle Steve on his ladder, I left him…Developer surface2021I mentioned this concept before, and I feel like it’s worth expanding…A symptom here is the tension around different qualities of API, like flexibility and ease of use. There’s this undulating dynamic that arises from this tension. Developers start with wanting an easy-to-use call that does all the work. Then, they tend to progress toward something more custom, wanting more flexibility. In many cases, the developers return from their custom solution back to the simpler APIs, seeking reliability and/or trying to shed their technical debt. Through this journey, the providers of the API will hear multiple seemingly conflicting requests from the same developer: make the API more easy — no, make it more flexible — no, go back to easy. With multiple developers at different points in the journey, this might feel like a cacophony, but a systems thinker in you will spot the polarity in the undulation: the moving back and forth is a process of seeking a dynamic equilibrium.

The cost of opinion2022Below is the reasoning that went into this little ditty. The first…

Declarative vs. imperative2024Another technique is something that Bernhard Seefeld is actively experimenting with: intentionally…Cheesecake and Baklava2022To compare and contrast, let’s look at Cascading Style Sheets. It’s fairly…Four layers2023An illustration for how this plays out is the abundance of the…What helped me here is the understanding that as API providers, we are better off not trying to “solve” this polarity for our customers. Instead we try to design APIs to be layered: provide two self-coherent stories that speak to each side of the polarity. The lower layer usually focuses on flexibility, exposing raw capabilities (here’s everything that’s possible), and the upper layer focuses on ease of use, incorporating best practices (here is a safe, efficient, and resilient way to use all those capabilities). Each tells its own story. The story of the flexibility APIs is as dry and to-the-point as possible, but with no bumpers to protect you from sharp edges. The story of the ease-of-use APIs is poetic and intuitive, but it also simplifies and elides some nuance.

Live as our customer2023This principle is something that feels very intuitive at first blush, but…Mindset transitions and coherencethe same dayI wonder if in the framing of organizational mindsets, there’s a pattern…When well-designed, these two stories don’t intersect. This helps reduce the chances of a developer who’s just looking for ease to wander into the woods of raw capabilities. But most importantly, it allows the stories to remain coherent, so that developers can tell between these different stories and make good choices in their journey to find that equilibrium.