🌆

skyjake.fi

API Evolution

📅 2022-11-06

🏷 Programming, the_Foundation

Adding support for PCRE2 in the_Foundation (and thus Lagrange as well) has got me thinking about APIs.

Generally speaking, the challenge in API design is to fit together internal and external views of a system. There's a tension between how the internal implementation wants things to be — for maximum efficiency — and the user wanting a friendly easy-to-understand black box. Choosing the right level of abstraction is crucial. However, the time dimension is critical as well: APIs should be resilient to allow unforeseen improvements and new features while not breaking user code. Changes may occur both internally and externally. A dead end is eventually reached when enough time has passed. The API has to be changed to accommodate the new situation.

From a developer's point of view, radically new versions of an API are laborious to take into use and the porting may introduce new bugs. However, forever supporting limited, poorly thought-out, or obsolete APIs is not feasible for library authors. There needs to be a compromise. (A nice one is to make a compatibility layer like sdl12-compat.)

There is powerful inertia keeping old versions of an API relevant: the more popular a library is, the more user code needs rewriting to get rid of the old API. Users have no urgency to switch to a new version of an API — they have other more pressing matters to deal with — and may just reject large changes if the perceived value isn't obvious. This makes it tricky for library authors to introduce major improvements.

In my case, porting the regular expression class to PCRE2 only required a few calls to be updated. Most of the work was trying to understand how the new API matches the old functionality: changed names, generalized types and parameters, new dynamic memory allocations. The amount of affected code was small, but it's easy to imagine the challenges and potential new bugs introduced in updating a larger code base.

CC-BY-SA 4.0