Polarity-based API layering

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.

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.

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.

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.

Leave a Reply