APIs as Ladders

This is an interesting article, but seems to fail to complete the point being made. Yes, having a very flexible API that has lots of possible entry points and extensions is useful to experts, but risks overwhelming those new to the API, especially if they are also new to the domain. Likewise having a convienent, inflexible API can lead to short term adoption at the expense of long term commitment.

Despite making both of these points, and even then going as far as to say you can package a more flexible API into less flexible but more immediately convienent parts arbitrarily, it doesn't quite complete the point by indicating what you really want to aim for is a layered API that allows you to start off with a convienent, high level wrapper and as you need more flexibility, peel off that layer specifically in the place you need it. As ever, talking in the abstract about such things make them seem easier than they are, but still a worthwhile goal.

It's slightly surprising the post doesn't quite make this point, considering that they directly link to Casey Muratori's talk on exactly this as a footnote: https://caseymuratori.com/blog_0024.

Separately, I also find it interesting that there are domains that seem to be deliberately eskewing the layered approach within a single API in favour of requiring separate users to write the higher level convience libraries. Notably some of the modern graphics APIs, including WebGL and WebGPU, which provide the 'lower level' access to graphics functionality, but expect most users to use a higher level library for interacting with them (BGFX, Raylib, BabylonJS, ThreeJS etc.).

Great article!

I wrote an article on API design way back in 2008 that advocated for "Scaleable" APIs, in terms of user-investment, which dovetails exactly w/ this concept of "Laddering" APIs:

> With this layered approach to File I/O, GScript users do not need to become familiar with the complicated Java I/O libraries to do simple and even moderately complicated things. Yes, there is now some redundancy, but each layer fulfills a particular band of the complexity/performance continuum. GScript programmers are only required to know as much about I/O as is necessary to solve the problem they have with acceptable performance.

https://guidewiredevelopment.wordpress.com/2008/10/05/api-de...

Your interface must be easy enough for a beginner. Your interface must be flexible enough to continue to be useful as your users' requirements change.

This should be true for your user interface and it should be true in your programmable interface.

The author mentioned SDKs in a passing comment, but it's really the crux of the solution and I think warrants more detail. SDKs allow you to implement language specific versions of APIs which can mask significant complexity and also make the functionality of the API accessible to a much broader group of developers within that language.

These are staircases, not ladders