MicroservicePatterns.com

Suggestions

  • PagePattern catalogAll patterns by category.
  • LabCircuit Breaker and Retries labCrash a dependency and tune the breaker.
  • LabSaga labFail a step and watch the compensations run.
  • PagePractice questionsScenario questions with explanations.
  • PageDesign reviewCheck your own architecture for anti-patterns.
Frontend

API Evolution Lab

A delivery app ships four versions over twenty weeks, and its users upgrade when they get round to it. Meanwhile the order API changes underneath them: a field is renamed and a new order status appears. Choose how each change ships, and watch which installed apps keep working.

Background: Backward-Compatible API Evolution, Backend for Frontend, Consumer-Driven Contract Testing.

Scenarios
The API change
The apps

Versions ship in weeks 1, 4, 9, 15. In week 9 the API renames deliveryDate to estimatedDelivery, which only version 3 and later read. In week 13 a new order status appears on 5% of orders, which only version 4 knows. About 4% of users never upgrade.

Starting
Version 1ships week 1Not releasedVersion 2ships week 4Not releasedVersion 3ships week 9Not releasedVersion 4ships week 15Not releasedOrder APIdeliveryDateestimatedDeliverystatus: RETURN_REQUESTED
–Users whose order screen fails
–Users asked to upgrade
–Order screens failing on an unknown status
–Users still on versions 1 and 2
0%100%Users by app version: 1, 2, 3, 4 from the bottom0%50%100%red: users failing · amber: asked to upgradewk 1wk 6wk 11wk 16wk 21
Guided experiments

Run these in order

  1. Rename the field in place

    Ship version 3 in week 9 and switch the API to the new field name the same day. Everyone still on versions 1 and 2, over 70% of users that week, gets a broken order screen. Unlike a web app, you cannot redeploy the apps on people's phones.

  2. Add the new field and remove the old one late

    Send both fields from week 9, and drop the old one in week 19. Almost nobody breaks, except the 4% or so who never upgrade: old phones and switched-off updates. Waiting longer never gets that number to zero.

  3. Add a minimum supported version

    When the old field goes, tell versions that need it to upgrade. The same users are affected, but they see a clear upgrade screen instead of a crash. That is the honest way to retire the last old versions.

  4. Keep the calendar, lose the users

    Same plan, but users upgrade at 10% a week instead of 30%. A third of users break in week 19. The date was a guess; the version data says it is far too early. Remove fields when usage says so, not when the calendar does.

  5. Read responses strictly

    Make every app fail on values it does not know. In week 13 the backend adds a new order status that only version 4 understands, and about one order screen in twenty fails for everyone else. Adding a value is only a safe change if clients read tolerantly.

  6. Translate in the BFF

    Let the backend for frontend give each app version the shape it expects. Nobody breaks and the domain services change freely, but the BFF now keeps two response shapes alive for as long as old versions exist.

This lab simplifies reality on purpose. All users upgrade at the same rate, every user opens the order screen every week, and a failing screen counts the same whatever the cause. Real apps also differ by platform, since iOS and Android users upgrade at different speeds, and a forced upgrade loses some users entirely, which the lab does not count.