Api-Design on Brian Faust

The Engine Prices Parcels, Not Copies

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

I dropped the package-copy shortcut during the rating engine’s development. If a shipment contained ten parcels, I wanted ten parcel records, not one record with copies: 10. Count-based pricing stayed. The alternative way of describing the things being priced didn’t.

This was an earlier input-model decision, not another change made during the Go port. It matters to the rest of the engine because parcels acquire references: a transport leg carries particular parcels, an item allocation belongs to a particular parcel, and a package-scoped rule needs that parcel’s facts. A multiplier doesn’t answer those questions without more conventions.

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 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, and the implementation is easier to read. It is probably the better name. That is also beside the point.

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.