skip to content

As lead of a retail-banking web app whose SPA and API ship from two teams' separate pipelines, who owns a contract change, and how is it ordered and rolled back?

level: principalimportance: should knowfreq 34%

answer

  1. pipelines land apart, not on cue
  2. API first, SPA behind a flag
  3. removals wait for rollback targets
  4. required: optional, then sent, then required
  5. roll back in reverse order

basics

~20 s

The API ships first; the SPA follows, using new fields behind a flag turned on once the API is live; removals and new requirements wait until no live or rollback-target SPA build needs the old shape. Rollback runs in reverse: SPA first.

solid answer

~50 s

Two pipelines cannot be made to land at the same moment, so I'd set one rule: the live API always serves the live SPA and the SPA build it would roll back to, and every contract change is planned as a sequence with its rollback written down. The side that needs the change writes that plan; the API team owns the published shape. A new response field: the API adds it, then the SPA ships reading it behind a flag, turned on once the API is verified live. A rename: the API serves both names, the SPA moves, and the old name goes only when no deployed SPA build, nor its rollback target, still reads it. A new required request field: optional on the API first, the SPA sends it, then required. Rollback runs in reverse: flag off or SPA back first, API last.

code

pseudocode · 12 lines
pseudocode
plan: rename overview field availableBalance -> available

1. API release A   : response carries availableBalance AND available
2. SPA release B   : reads available, behind flag use-available (off)
3. flag on         : in each environment, after release A is verified there
4. wait            : until no deployed SPA build and no SPA rollback target reads availableBalance
5. API release C   : drop availableBalance
6. SPA release D   : remove flag use-available

rollback:
  trouble after step 3  -> flag off; redeploy pre-B SPA only if still needed
  roll back API A       -> only after flag is off or SPA is back before B

go deeper

for a junior

Recall that the browser app and its API deploy separately, so one of them goes live before the other.

for a middle

Explain the three cases, a new field, a rename and a new required request field, and which side ships at each step.

for a senior

Show the rollback path: a flag as the fast switch, the SPA before the API, and why a removal waits for the SPA's rollback target.

for a principal

Own the rule and its cost: who writes the plan, how many releases a rename takes, and when a versioned endpoint or a frontend-owned layer beats the ordering.

## Why the seam needs an order The **SPA/API seam** is the contract between a browser app and the API it calls. In this retail-banking web app the two ship from **separate pipelines owned by two teams**. Two pipelines cannot be relied on to land at the same instant: one finishes minutes or days before the other, and either can fail, be paused or roll back on its own. A "coordinated" same-minute deploy only shrinks the broken window; it cannot close it. So the design needs one invariant: **at every moment, the live API serves the live SPA and the SPA build it would roll back to.** Every ordering rule below follows from it. ## Who owns a contract change - **The SPA team states the need**: which screen needs which field, in which shape. - **The API team owns the published shape**: naming, types, and how it fits the rest of the API. - **The side that needs the change writes the plan**: the sequence of releases, the flag, the rollback, and the condition for the final clean-up step, each with an owner. - **The contract lives in one shared, reviewed description** that both teams change by review. Whether the SPA consumes generated types from it, and which automated check catches a breaking edit, are neighbouring subjects; the plan is what this seam needs. ## The ordering, case by case | Change | Release 1 | Release 2 | Release 3 | |---|---|---|---| | New response field | API adds the field | SPA reads it behind a flag; flag on once the API is live | Remove the flag | | Renamed response field | API serves old and new names | SPA reads the new name | API drops the old name once no live or rollback-target SPA build reads it | | New required request field | API accepts it as optional | SPA sends it | API makes it required once every live and rollback-target SPA build sends it | | Removed endpoint | SPA stops calling it | API removes it once no live or rollback-target SPA build calls it | none | Two notes. First, a new field is harmless to the live SPA only if the SPA ignores fields it does not know, which is the tolerant-reader subject next door; the phase vocabulary of adding before removing is expand-and-contract, also next door. Second, the same order applies to a GraphQL schema: the field arrives first and is removed last. ## Flags decouple deploy from release 1. The SPA ships the code that uses the new field **dark**, behind a flag that is off. 2. The flag turns on in each environment only after the API change is verified live there. 3. If something misbehaves, turning the flag off is the fastest rollback, measured in seconds rather than a pipeline run. 4. The flag is removed in a later release, as a written clean-up with an owner, so it does not become permanent. ## Rollback runs in reverse - **SPA first**: flag off, or redeploy the previous SPA build. - **API last, and only if needed**: an API rollback that removes something the live SPA reads is itself a breaking change. - **Removals wait for rollback targets**: once the API drops the old name, the previous SPA build can no longer be restored safely, so the removal waits until the SPA team confirms that build is no longer a rollback target. - **Per environment**: the same order in test as in production, so the rehearsal matches the real thing. How long pages opened before a release keep running the old build is a separate subject; this plan covers the order of the two deployments. ## The trade-off a lead owns The rule is not free: - a rename takes three releases across two teams, and flags need clean-up; - the plan slows small changes that one team could have done in one afternoon. Alternatives exist. A versioned endpoint lets the API ship an incompatible shape beside the old one, at the cost of running both. A backend-for-frontend owned by the SPA team moves the most frequent changes inside one team, although the BFF still deploys separately from the SPA and the same order applies at its own seam. The lead's call is which changes deserve the ceremony; for a banking app's money paths, nearly all of them do.

  • The API team proposes skipping the flag and shipping both sides 'close together'. What do you say?
    Close together still leaves a window, and either pipeline can fail or roll back alone. Without a flag, the SPA's only switch is another deploy. The flag costs a clean-up task; the alternative is a broken screen whenever the two land out of order.
  • Who decides that the old field can finally be removed?
    The SPA team signs off, because only it knows which builds are live or kept as rollback targets; the API team then removes the field. Writing that condition into the plan, with a named owner, keeps the removal from happening early or being forgotten.
  • Does the order change if the API is GraphQL instead of REST?
    No. The schema gains the field first, the SPA's queries select it behind a flag, and the field is removed only after no live or rollback-target SPA build queries it. The schema-side deprecation mechanics are their own subject; the sequencing across the two pipelines stays the same.

  • Shipping the SPA first and relying on the API to follow within the hour
  • Coordinating both pipelines to deploy in the same minute as the safety plan
  • Dropping the old field as soon as the new SPA build is live
  • Rolling the API back first when a release using its new field misbehaves
  • Making a request field required before every live SPA build sends it