Api-Design on Brian Faust

Boolean Parameters Hide Different Operations

Sun, 01 Mar 2020 00:00:00 +0000

This method call is legal:

$exporter->execute($accountId, true, true);

It is also semantically wrong.

The first boolean in the retained exporter meant “source billing details from the effective payer.” The payload still targeted the original account and kept that account’s operational fields. The second boolean meant “the source’s billing mode is an authoritative instruction.”

An effective-payer export described who pays. It was not allowed to change the original account’s billing mode. The true, true combination therefore had to be neutralized by a later guard.

Renaming a Field Is a Protocol Migration

Thu, 01 Nov 2018 00:00:00 +0000

An API changes serviceIds to deliveryOptionIds. The new name describes the domain better. The implementation becomes easier to read.

An existing client still sends:

{
 "serviceIds": ["express"]
}

The request now fails validation before any application code runs.

Nothing about the client’s intent changed. The server chose a cleaner name and turned that preference into a breaking protocol change.

Once another process sends a field, renaming it is no longer a refactor. It is a migration involving deployed callers whose release schedule the server may not control.