The fractal dragontwo days beforeI’ve already shared this piece elsewhere, but might as well post it…Hosting and hosted API design perspectives

Polarity-based API layering2021While discussing API design, one pattern that caught my eye was polarity-based…Developer surface2021I mentioned this concept before, and I feel like it’s worth expanding…When discussing API design strategies, I keep running into this distinction. It seems like a developer experience pattern that’s worth writing down.

Caring for elephants2022Are the APIs we offer predictable, reliable, stable? Can we guarantee providing…Consider these two perspectives from which API designers might approach the environment. The first perspective presumes that the API implementation is hosting the developer’s code, and the second that the API implementation is being hosted by the developers’ code.

Four layers2023An illustration for how this plays out is the abundance of the…From the first perspective, the API designer sees their work as making a runtime/platform of some sort. The developer’s code needs to somehow enter a properly prepared environment, execute within that environment, consuming the designed APIs, and then exit the environment. A familiar example of designing from this perspective is the Web browser. When the user types the URL, a new environment is created, then the developer’s code enters the environment through the process of loading, and so on. Every app (or extension) platform tends to be designed from this perspective. Here, the developer’s code is something that is surrounded by the warm (and sometimes not very warm) embrace of the APIs that represent the hosting environment.

When I design APIs from the second perspective, the developer’s code is something that hosts my code. I am still offering an API that is consumed by someone else, but I don’t set the rules or have opinions on how the surrounding environment should work. I just offer the APIs that might be useful. Typically, this perspective results in designing libraries and frameworks. For example, I might write a set of helper functions that provide a better handling of date math in Javascript. This tiny library can run in any Javascript environment, be that server or client. It can be hosted by any app or site that needs date math. This “run wherever, whatever” is a common attribute of this API design perspective.

The tension between growth and control2023I alluded to this tension before, but it was somewhat buried in…Growth, control, and tricycles2021Riffing on Alex Komoroske’s excellent set of cards on compounding loops, there’s…There is the growth/control tension that seems to map into these two perspectives. Hosting perspective exhibits the attitude of control, while hosted perspective favors the force of growth. As with any tension, complexity arises along the spectrum between the two.

The cost of opinion2022Below is the reasoning that went into this little ditty. The first…A Javascript framework (a hosted API) that has strong opinions about its environment (wanting to be a hosting API) will have challenges maintaining this environment, since it is ultimately incapable of creating it. Back in the day when I still worked in the Web Platform, I’ve had many discussions with framework authors who wanted us Web Platform folks to give them the option to create clean environments. This desire to shift from hosted to hosting was not something I recognized back then and now wish this article existed to help me reason through the struggle.

Shadows and Curses2022The second curse can be seen as the interplay between “ 🔮…Similarly, a hosting API that wants to grow will be pressed to make the environment more flexible and accommodating. Going back to the example above, we Web Platform folks were experiencing that pressure, the force that was pulling us away from hosting and toward a hosted API design perspective. After that shift, the code that renders Web pages — the fundamental building block of the Web Platform environment — would become just one of the libraries to pick and choose from.

Growing dandelions2022A couple of weeks ago, I talked about r/K-selection and mentioned two…The miracle count2021While working on a technical design this week, my colleagues and I…Heuristics will be discerned and codifiedtwo days after, links hereBecause heuristics are so tempting, this pattern is very common. Here’s the…It is also important to note that, using Hamilton Helmer’s classification, the existence of a hosting environment is a form of cornered resource. It’s something that only becomes possible to have when the API designer has the luxury of a significant quantity of willing hosted participants. In the absence of eager hordes of developers knocking on your door, taking a hosting API design perspective is a high miracle count affair. When thinking about this, I am reminded of several ambitious yet ultimately unsuccessful efforts to “create developer ecosystems.” There are ways to get there, but starting out with the hosting API design perspective is rarely one of them.