Green APIs, Broken Handoffs
Sample payloads beat architecture slides
An end user does not experience "service returned 200." They experience success toast - nothing in the account - while four service dashboards stay green. Article 01 mapped the front door; this note goes under the hood: where state must hand off, and why "my team's API is green" is insufficient for launch sign-off.
Here's what this piece covers: one broken seam, commit bbba7ea (2026-04-07), the integration surface map pattern, and three gates I would enforce as a lead.
Part of Field Notes: agentic delivery.
1. The leadership problem
Modern product surfaces are not one application. They are a graph of backends - identity, records, entitlement, partner data, CRM - with the client calling peers directly. No single BFF wraps the handoffs.
When two services look healthy in isolation, production still fails at the seam: idempotency on retry, pending records syncing downstream, entitlement codes propagating after the upstream step completes.
Wrong: "Service A talks to the CRM."
Right: "Here is the sequence for complete → write → profile sync → support handoff - and the three failure modes we found when we read sample payloads."
The anti-pattern is endpoint checklist theater - every service "integrated" while the path still fails.
2. What the git history shows
Five days after the MVP map landed, commit bbba7ea (2026-04-07) added an integration corpus: architecture notes, handoff design, an executive one-pager, and data-dump.md - 987 lines of sample payloads.
The data dump was the learning beat. Specs said fields aligned; dumps showed nulls, wrong enums, and timing gaps between upstream record state and CRM create.
Specs lie politely. Payloads do not:
record SyncPayload(String externalId, String status, String entitlementCode) {}
static Optional<String> silentFailure(SyncPayload p) {
if (p.externalId() == null) return Optional.of("null externalId");
if (!"ACTIVE".equals(p.status())) return Optional.of("unexpected status: " + p.status());
if (p.entitlementCode() == null || p.entitlementCode().isBlank())
return Optional.of("missing entitlementCode");
return Optional.empty();
}3. What I learned
Three lessons I still reuse on launch programs:
A write is a chain, not a POST. Create account → attach upstream record → write entitlement → read back the account. A green POST on /register proves nothing about read-back.
The client calls peers directly. There is no integration team hiding behind one API. Seam ownership must be named per hop - foreshadow integration tests are chains.
Environment parity blocks more than frontend bugs. CRM sandbox access, pending queues, and field-level security stopped Phase 2 seam work for weeks while UI looked fine.
| Path step | Owning concern | External system |
|---|---|---|
| Primary action complete | Records service | Upstream provider |
| Write from upstream record | Entitlement + records seam | - |
| Result visible in account | Entitlement read-back | - |
| Support escalation | Entitlement → CRM | CRM |
| Partner / service lookup | Org + geo services | Mixed third-party |
4. Named pattern: integration surface map
Integration surface map - who owns each hop, what the contract is, what breaks silently at the seam.
Not a system-context poster on a wall. A living map tied to workflow IDs and sample payloads:
This map drove how we sequenced 63 SIT workflows - team scope first, seams second, end-to-end paths third (article 05).
5. What I'd do as a lead
- Require an integration map for every launch - not just an architecture slide. Include sample payloads early.
- Gate Phase 2 SIT on seam owners, not feature owners alone. "Not our service" is not an exit criterion.
- Keep a watch list for pending writes and entitlement ripple defects - they re-emerge at CRM handoffs (later: blocker matrix).
Further reading
- Fifty pages, one map - master flow (
59334b2) - Prove the path, not the POST
- Planning anchor: commit
bbba7ea· 2026-04-07
