Estimating a third-party API swap

The story where the new vendor's API looks identical until you start migrating the data.

The pitch for swapping vendors is always the same: the new API is cleaner, faster, cheaper. The trap is that the old API's quirks are load-bearing. The codebase has two years of "this is a string but it's actually a date in their format," "this returns null when it means zero," "this rate-limits silently" — and a clean swap means reproducing every one of those quirks against the new vendor's behavior, which is different in ways nobody has documented.

The estimate has to budget for the dual-run: the old and new vendors running side-by-side, with output comparison, until the team has confidence the new one matches. That phase is often longer than the implementation. Stories that don't budget for it ship the new vendor and discover the gaps the next time a customer's data hits an edge case.

What gets said in the room

Backend: "The new SDK is nicer. The basic calls are a day each."

Lead: "What about the historical data they're holding for us?"

SRE: "Are we running both vendors at once, or cutting over?"

Backend: "Their webhook format is different. So is the auth."

QA: "How do we verify equivalence — diff the responses for a week?"

Questions worth asking before voting

  • Is there historical data at the old vendor that needs to come with us?
  • Auth differences — API keys, OAuth, signed requests?
  • Webhooks: do the events map cleanly, or do we translate?
  • Dual-run period: how long, and what's "good enough" to cut over?
  • Rate limits and pricing model on the new vendor — same shape, or different?
  • Rollback: can we go back if the new vendor turns out to be worse?

Like database migrations, the SQL is fast and the rollout is the work. Open a session when the dual-run plan is sketched.