Skip to content

PATTERN Cited by 1 source

Two-pass API migration

Two-pass API migration is the discipline of migrating each API across two explicit passes: a first pass that makes the API work well enough for internal dogfood users (typical flows, obvious cases), and a second pass — "perhaps weeks later" — that fixes integration tests, permission checks, and edge cases to make it customer-ready. The two passes are decoupled so dogfood rollout is not gated on full correctness.

Canonical wiki instance: Slack's Unified Grid (systems/unified-grid, Source: sources/2024-08-26-slack-unified-grid-how-we-re-architected-slack-for-our-largest-customers).

The verbatim framing

"In keeping with prototyping the path, we asked engineers to take two passes over each API: a first pass to make the API work well enough for internal usage, and then — perhaps weeks later — a second pass to ensure the integration tests, permissions checks and other edge-cases behaved correctly. This two-phase approach allowed us to manually verify and get a feel for functionality which was not entirely ready for primetime."

Why the two-pass split works

A large API-migration project that requires every API to be customer-ready before any API ships internally has a fundamental coordination problem: you can't dogfood until everything is done, and "everything" includes thousands of APIs. Dogfood is the prototype-the-path feedback mechanism; gating it behind full correctness defeats the methodology.

The two-pass split decouples:

  1. "Works for typical usage" — enough to be used internally. Core flows work; most permissions are right; common code paths are tested.
  2. "Correct at the margins" — integration tests pass, permission checks cover edge cases, failure modes behave predictably, error messages are right.

Internal users can tolerate #1 without #2. Customers cannot. The two-pass split gives you the benefit of #1 (dogfood feedback) without the cost of waiting for #2 across thousands of APIs.

How it composes with prototype-the-path

The two passes map onto the concentric-ring rollout (patterns/prototype-the-path):

  • First pass complete → API is compatible with the Unified Grid client for internal (employee) use. Ring: engineering org → Summer 2023 company-wide dogfood.
  • Second pass complete → API is customer-ready. Ring: Fall 2023 customer rollout → March 2024 complete.

"Most importantly, we put together a detailed guide with step-by-step instructions for ensuring that an API behaves correctly in Unified Grid, including the strategies for fixing APIs listed in the 'Prototyping the path' section."

The "detailed guide" is the discipline that makes two-pass consistent across thousands of APIs and scores of engineers — without it, each engineer invents their own definition of "first pass."

The three API-fix strategies (a supporting taxonomy)

At Slack, any API's two-pass migration involves choosing one of three strategies (Source: sources/2024-08-26-slack-unified-grid-how-we-re-architected-slack-for-our-largest-customers):

  1. Drop the old routing context entirely if the underlying data layer is already sharded independently.
  2. Prompt the user to provide the routing context as an explicit parameter if the API genuinely needs it.
  3. Iterate over the relevant contexts as a fallback (bounded by concepts/bounded-fan-out-relevance-cap).

Each of the three strategies has a first pass (make it work for the common case) and a second pass (handle edge cases — permission combinations, workspace-membership edge cases, error propagation).

When the pattern pays off

  • Thousands of APIs to migrate. The two-pass split's coordination benefit scales with surface size.
  • A clear "internal user" distinction. You can dogfood the first-pass result; the internal-users-vs-customers boundary is real and enforceable (feature flag, login type, deploy channel).
  • Integration tests are reusable. Ideally via a context- axis swap (patterns/parallel-integration-test-suite-for-context-switch) — the broken tests after the first pass become the actionable list for the second pass.
  • Second-pass backlog is visible. The "spreadsheet to track the number of APIs and permission checks we needed to fix" is not decorative; it is the coordination tool that makes "perhaps weeks later" accountable.

When the pattern is wrong

  • Compliance / safety gate on first-pass completeness. If internal-use cannot happen before all edge cases are handled (e.g. a financial API where a permission miss is a customer loss), you can't split passes.
  • The API is small / rarely called. Overhead of tracking two passes exceeds benefit.
  • No clear internal-user population. Without dogfood, the first pass is not validated by real usage — it just becomes "untested code in production."

The coordination substrate

The two-pass discipline depends on:

  • Per-API tracking — spreadsheets, dashboards, a migration backlog.
  • API-framework flag — a per-API "marked compatible with new client" toggle so engineers know what's graduated.
  • Documented migration patterns — so first-pass work is uniform across teams.
  • A rollout gate — customer rollout cannot begin until a threshold of second-pass completions is met.

Seen in

  • sources/2024-08-26-slack-unified-grid-how-we-re-architected-slack-for-our-largest-customers — Slack's canonical two-pass API migration during Unified Grid. First pass for internal use; second pass for customer correctness (integration tests, permission-check edge cases, other edge cases). Supported by API-framework compatibility flag, detailed migration guide, spreadsheet-based tracking, and convenience helpers (permission-check helpers for cross-workspace channels).
Last updated · 470 distilled / 1,213 read