Bsrgvty

We have an API function that breaks down a total amount into monthly amounts based on given start and end dates.

// JavaScript

function convertToMonths(timePeriod) 
 // ... returns the given time period converted to months


function getPaymentBreakdown(total, startDate, endDate) 
 const numMonths = convertToMonths(endDate - startDate);

 return 
 numMonths,
 monthlyPayment: total / numMonths,
 ;

Recently, a consumer for this API wanted to specify the date range in other ways: 1) by providing the number of months instead of the end date, or 2) by providing the monthly payment and calculating the end date. In response to this, the API team changed the function to the following:

// JavaScript

function addMonths(date, numMonths) 
 // ... returns a new date numMonths after date


function getPaymentBreakdown(
 total,
 startDate,
 endDate /* optional */,
 numMonths /* optional */,
 monthlyPayment /* optional */,
) 
 let innerNumMonths;

 if (monthlyPayment) 
 innerNumMonths = total / monthlyPayment;
 else if (numMonths) 
 innerNumMonths = numMonths;
 else 
 innerNumMonths = convertToMonths(endDate - startDate);
 

 return 
 numMonths: innerNumMonths,
 monthlyPayment: total / innerNumMonths,
 endDate: addMonths(startDate, innerNumMonths),
 ;

I feel this change complicates the API. Now the caller needs to worry about the heuristics hidden with the function's implementation in determining which parameters take preference in being used to calculate the date range (i.e. by order of priority monthlyPayment, numMonths, endDate). If a caller doesn't pay attention to the function signature, they might send multiple of the optional parameters and get confused as to why endDate is being ignored. We do specify this behavior in the function documentation.

Additionally I feel it sets a bad precedent and adds responsibilities to the API that it should not concern itself with (i.e. violating SRP). Suppose additional consumers want the function to support more use cases, such as calculating total from the numMonths and monthlyPayment parameters. This function will become more and more complicated over time.

My preference is to keep the function as it was and instead require the caller to calculate endDate themselves. However, I may be wrong and was wondering if the changes they made were an acceptable way to design an API function.

Alternatively, is there a common pattern for handling scenarios like this? We could provide additional higher-order functions in our API that wrap the original function, but this bloats the API. Maybe we could add an additional flag parameter specifying which approach to use inside of the function.

Seeing the implementation, it appears to me what you really require here is 3 different functions instead of one:

The original one:

function getPaymentBreakdown(total, startDate, endDate) 

The one providing the number of months instead of the end date:

function getPaymentBreakdownByNoOfMonths(total, startDate, noOfMonths) 

and the one providing the monthly payment and calculating the end date:

function getPaymentBreakdownByMonthlyPayment(total, startDate, monthlyPayment) 

Now, there are no optional parameters any more, and it should be pretty clear which function is called how and for which purpose. As mentioned in the comments, in a strictly typed language, one could also utilize function overloading, distinguishing the 3 different functions not necessarily by their name, but by their signature, in case this does not obfuscate their purpose.

Note the different functions don't mean you have to duplicate any logic - internally, if these functions share a common algorithm, it should be refactored to a "private" function.

is there a common pattern for handling scenarios like this

I don't think there is a "pattern" (in the sense of the GoF design patterns) which describes good API design. Using self-describing names, functions with fewer parameters, functions with orthogonal (=independent) parameters, are just basic principles of creating readable, maintainable and evolvable code. Not every good idea in programming is necessarily a "design pattern".

Additionally I feel it sets a bad precedent and adds responsibilities to the API that it should not concern itself with (i.e. violating SRP). Suppose additional consumers want the function to support more use cases, such as calculating total from the numMonths and monthlyPayment parameters. This function will become more and more complicated over time.

You're exactly correct.

My preference is to keep the function as it was and instead require the caller to calculate endDate themselves. However, I may be wrong and was wondering if the changes they made were an acceptable way to design an API function.

This isn't ideal either, because the caller code will be polluted with unrelated boiler plate.

Alternatively, is there a common pattern for handling scenarios like this?

Introduce a new type, like DateInterval. Add whatever constructors make sense (start date + end date, start date + num months, whatever.). Adopt this as the common-currency types for expressing intervals of dates/times throughout your system.

Sometimes fluent-expressions help on this:

let payment1 = forTotalAmount(1234)
 .breakIntoPayments()
 .byPeriod(months(2));

let payment2 = forTotalAmount(1234)
 .breakIntoPayments()
 .byDateRange(saleStart, saleEnd);

let monthsDue = forTotalAmount(1234)
 .calculatePeriod()
 .withPaymentsOf(12.34)
 .monthly();

Given enough time to design, you can come up with a solid API that acts similar to a domain-specific-language.

The other big advantage is that IDEs with autocomplete make almost irrevelant to read the API documentation, as is intuitive due its self-discoverable capabilities.

There are resources out there such as https://nikas.praninskas.com/javascript/2015/04/26/fluent-javascript/ or https://github.com/nikaspran/fluent.js on this topic.

Example (taken from the first resource link):

let insert = (value) => (into: (array) => (after: (afterValue) => 
 array.splice(array.indexOf(afterValue) + 1, 0, value);
 return array;
));

insert(2).into([1, 3]).after(1); //[1, 2, 3]