Integration on Brian Faust

Parallel Implementations Are Not a Replacement Seam

Mon, 01 Apr 2019 00:00:00 +0000

An old shipping integration and its proposed replacement lived beside each other. Both had an interface. Both had a driver, request builders, and tests. That looked like a seam.

When the replacement was finally made canonical, the change still crossed dozens of files. The old interface disappeared, the new one moved, the canonical driver changed its pickup and shipment flows, and a parallel driver tree was deleted. Follow-up work then corrected a request shape and added serialization tests.

A Capability Interface Is Smaller Than a Vendor Client

Sat, 01 Dec 2018 00:00:00 +0000

A controller needs to register an order webhook. It constructs a vendor SDK connection, accesses a dynamic resource property, calls its creation method, names the remote event, chooses response fields, and catches the SDK’s base exception.

Its test needs to intercept construction of that concrete connection and mock a dynamic property chain. The two useful behavior tests are skipped with the same explanation: the code needs an interface and dependency injection.

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.

A Cache Must Distinguish Empty from Unavailable

Mon, 01 Oct 2018 00:00:00 +0000

A cached search returns two pickup locations. One location is deleted locally, but the search keeps returning both.

The tempting repair is a shorter time to live. That trades a known correctness bug for a shorter known correctness bug. The system already knows the cached answer is false; waiting five minutes instead of an hour does not make it less false.

The opposite failure looks similar. A remote lookup returns nothing during an outage. Replacing the cache with an empty list would remove locations which may still exist.

Partial Work Needs a Child Ledger

Sat, 01 Sep 2018 00:00:00 +0000

A queue job receives 1,000 events in one remote response. It dispatches 600 child jobs, then times out.

The parent row says processing failed. Some children have already finished. Others are waiting in the queue. The remaining 400 were never dispatched. A counter can report 573 completed events, but it cannot say which 573 they were.

Running the parent again may duplicate the first 600. Leaving it alone loses the last 400. Neither choice is defensible because the system retained a total and discarded the membership behind it.

Retry Budgets Multiply Across Layers

Wed, 01 Aug 2018 00:00:00 +0000

An HTTP connector allows three attempts. The queue job calling it also allows three attempts.

When the remote service keeps failing, the job does not make three calls. It makes nine:

job attempt 1 -> connector calls 1, 2, 3
job attempt 2 -> connector calls 4, 5, 6
job attempt 3 -> connector calls 7, 8, 9

Both settings look modest in isolation. The remote system receives their product.

A Rate Limit Belongs to All the Workers Sharing It

Sun, 01 Jul 2018 00:00:00 +0000

One polling job receives a 429 response saying to try again in fifteen seconds. It releases itself for fifteen seconds.

During that pause, twenty other workers poll the same provider. They have not seen the response, so each sends another request into the closed window.

The first job obeyed the limit. The application did not.

Find the scope before choosing the delay

A rate limit applies to some shared identity: an API credential, account, tenant, endpoint family, source address, or a combination of them. Every worker using that identity spends the same remote capacity.

An Idempotency Key Is Not an Identity

Fri, 01 Jun 2018 00:00:00 +0000

A booking test sends the same request twice with the same idempotency key. The remote booking service is called once. Both callers receive the same successful response.

Then one field changes while the key stays the same. The remote service is still called once, but the second request receives a conflict instead of the first result.

The key did not establish sameness. It only gave the application somewhere to look.

A Webhook Delivery Is Not a Unique Event

Tue, 01 May 2018 00:00:00 +0000

A subscription callback had already created this local record:

carrier: external-freight
subscription_id: sub-demo-17
secret: old-secret
expires_at: 2018-05-08T12:00:00Z

The sender delivered another validation message for sub-demo-17, now with a new secret and expiry. The handler tried to insert a second row. A unique constraint rejected it, so the activation step never ran.

The database was right. The handler had mistaken another delivery for another subscription.

Start with the identity the sender repeated

A webhook request is evidence that a message was delivered. It is not evidence that this message has never arrived before.

Map External Data Before It Enters Your Model

Sun, 01 Apr 2018 00:00:00 +0000

A payment callback arrives with these fields:

{
 "status": "COMPLETED",
 "amount": 7.79,
 "currency": "EUR",
 "reference": "session-demo-8",
 "transaction": "remote-demo-31",
 "message_time": "2026-04-01T09:15:00Z"
}

The application does not need a COMPLETED string or a floating-point amount. It needs a trusted result: which local operation completed, for how much, in which currency, under which remote identity, and at what instant.

Passing the decoded array into business code postpones that translation. It does not avoid it.

Authenticity comes before interpretation

The retained callback boundary receives a JSON string and a message authentication code. It rejects a missing or invalid code before the payment driver finalizes anything.

An HTTP 200 Does Not Mean the Operation Succeeded

Mon, 01 Jan 2018 00:00:00 +0000

Two requests reach the same JSON application.

The first lacks authentication. The server returns HTTP 200 with this body:

{
 "status": 0,
 "error": {
 "code": 401,
 "message": "Unauthenticated"
 }
}

The second is authenticated but lacks permission to browse a collection. It also returns HTTP 200, this time with an empty array:

[]

Both behaviors are pinned by retained tests. Neither can be interpreted from the status code alone. Worse, the empty array is indistinguishable from an authorized search which genuinely found nothing.

An Identifier Should Outlive Its Storage Engine

Sat, 01 Jul 2017 00:00:00 +0000

A billing export once had enough information to reconstruct a missing account, but not enough to name it.

The account still existed in an older system. Its stable identifier reached the export action. No matching row existed in the newer application’s user table, so the action built a temporary object with safe fallback details. That object had a synthetic local identifier, but its export identifier remained null. Later, a queued data object required that identifier to be a string and rejected the payload.