API Gateway Platform  ·  View 03 of 21  ·  People and journeys

Actors and Their Core Journeys

Eight actors, three of which are machines and two of which can break production faster than any person here.

Editable source SVG draw.io All views
People outside the company Integration developer ~4,000 active / month Goal — Get a key and make a call that works before I lose interest in your product. Core journeys First successful call target Debug a 429 without filing a ticket Rotate a key with no downtime Partner engineer 40 partners, mTLS Goal — Know months ahead if you are going to change something under me, and be able to stay put if I cannot move yet. Core journeys Survive a version migration Pin to a version by agreement People inside the company API product owner 120 services Goal — Ship v2 and retire v1 without finding out who was still calling it by breaking them. Core journeys Publish, canary, deprecate, sunset See who is still on the old version Platform SRE on call, 24/7 Goal — Tell in one glance whether this is the gateway's fault or an upstream's, and revert in one action if it is mine. Core journeys Revert a bad config in 30 s Evacuate a region Separate a 502 from a 429 Security engineer policy owner Goal — Revoke a leaked credential everywhere in under a minute, and prove afterwards what it did. Core journeys Revoke a credential globally Answer an audit from the log Actors that are not people Rollout controller continuous Goal — Halt a canary on the evidence, before anyone is paged about it. Core journeys Score a canary window Revert to last known good Health checker every backend Goal — Take an unhealthy backend out of rotation before a caller finds it. Core journeys Eject and re-admit a backend Config distributor versioned snapshots Goal — Get a new configuration version onto every proxy, and know which ones have it. Core journeys Distribute and confirm a version Actors and Their Core Journeys Person or role Journey / task Security / platform Three of the actors are machines. Two of them can break production faster than any of the people. v 1.0 · owner Integration Platform Architecture · date 2026-09

What this view is for

  • A gateway's users are overwhelmingly people the company has never met, writing code against documentation, at a moment when they can still walk away.
  • The integration developer's goal is stated in their voice because it sets the whole developer-experience requirement: a bare 401 ends the evaluation.
  • The rollout controller and the config distributor are actors because they take consequential actions without a human in the loop.

Assumptions

  • ≈ 4,000 integration developers active per month; 40 partner organisations on mTLS.
  • One SRE rota covers the platform globally, so "tell me whose fault it is" is a load-bearing requirement, not a nicety.

Risks

  • The partner engineer's goal — advance warning and the ability to stay put — conflicts with the API owner's goal of retiring v1. Views 05 and 19 are where that conflict is resolved, by a dated pin rather than a slipped date.
◀  High-Level Architecture All views Journey — The First Successful Call  ▶
Solution Architecture v1.0 · Google Cloud · Integration Platform Architecture · 2026-09 · 21 views · 18 architecture decision records03-actors-and-journeys