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, a driver, request builders, and tests. From the directory tree, 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. Instead, 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. That is a lot of vendor vocabulary for one product decision.

The test is no better. It has to intercept construction of that concrete connection and mock a dynamic property chain. Two useful behavior tests ended up skipped with the same explanation: the code needed 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, 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.

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. A TTL is not invalidation with worse timing.

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 still receives their product. Three attempts multiplied by three attempts is nine calls, regardless of how harmless each configuration file looks.

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, so it releases itself for fifteen seconds. During that pause, twenty other workers poll the same provider. They have not seen the response, and 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, and 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 to reject it. The handler had mistaken another delivery for another subscription, then treated the constraint as the problem.

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 merely postpones that translation. It does not avoid it; it just makes every later caller participate.

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:

[]

Regression tests pin both behaviors. Neither can be interpreted from the status code alone, and the empty array is worse: it 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 and its stable identifier reached the export action. What did not exist was a matching row in the newer application’s user table.

The action worked around that absence by building a temporary object with safe fallback details. It even gave the object a synthetic local identifier. The field used as the export identity remained null, though, and a queued data object later rejected the payload because that field had to be a string. The fallback had solved the missing attributes while losing the one fact the export actually needed: which account it was about.