Keep your API elegant only in its signature

One paragraph from legacy React design principles document has stuck with me ever since stumbling upon it the first time:

We try to provide elegant APIs where possible. We are much less concerned with the implementation being elegant. The real world is far from perfect, and to a reasonable extent we prefer to put the ugly code into the library if it means the user does not have to write it. When we evaluate new code, we are looking for an implementation that is correct, performant and affords a good developer experience. Elegance is secondary.

The main takeaway for me was that elegance in the API usage matters much more than elegance within the black box of the function or the component.

This came up in a recent work discussion regarding an internal API client for an integration service. The initial implementation looked something like this:

class ApiClient {
  async getProfileDetails(id: string) {
    const basicDetails = await getBasicDetails(id);
    if (basicDetails.status !== "active") {
      return null;
    }
    const enhancedDetails = await getEnhancedDetails(id);
    // various data normalization subroutines here
    return {
      ...basicDetails,
      ...enhancedDetails
    }
  }
}

This suffers from a pretty clear case of await waterfalls, i.e. this function being much slower than it needs to be for the usual case of an active profile due to the second await only starting once basic details query has already resolved.

A quite simple parallelization improvement while still keeping the minimum execution time the same would be as such (this also assumes that we don’t care about making an extra enhanced details call):

class ApiClient {
  async getProfileDetails(id: string) {
    const enhancedDetailsPromise = getEnhancedDetails(id);
    const basicDetails = await getBasicDetails(id);
    if (basicDetails.status !== "active") {
      return null;
    }
    const enhancedDetails = await enhancedDetailsPromise;
    // various data normalization subroutines here
    return {
      ...basicDetails,
      ...enhancedDetails
    }
  }
}

Here we launch the enhanced details promise immediately in the background, while only awaiting on it (and caring about the result) once the basic details check has completed.

The first version is clearly more elegant and simpler, whereas the second version could resolve twice as fast due to parallelization. The API user should be confident that the implementation is doing things that make sense as performantly as possibly and the API user should only care about the interface contract and the promises it makes, and thus I think the second version is in this case better.