Technical Report

REST API v2 Migration

Analysis of migrating 14 internal services from v1 to v2 API — scope, risks, and recommended rollout sequence.

Summary

Key metrics and current status at a glance.

14 Services in Scope

Across 4 teams — payment, auth, notification, analytics

6 Migration Complete

Low-risk services migrated in Phase 1 without incidents

8 Remaining

Including 2 critical-path services requiring extended testing

Background

Why this migration is happening and what changes.

The v1 API was designed for a monolithic architecture and does not support per-resource pagination, field filtering, or idempotency keys — all required for the new distributed payment pipeline. v2 introduces a consistent response envelope, cursor-based pagination, and HMAC request signing.

Breaking changes in v2 affect 3 of the 14 services: the auth token format changed from JWT to opaque tokens, webhook payloads moved to a new schema, and error codes were renumbered. All other services have backwards-compatible differences only.

Remaining Services

Status and complexity assessment for the 8 services still on v1.

Payment Core

Breaking change

Uses JWT auth tokens and relies on the v1 webhook schema for settlement callbacks. Requires coordinated cutover with the settlement team. Estimated effort: 5 days.

Notification Service

Moderate

Webhook consumer. New payload schema requires updated deserialization logic. No auth changes. Estimated effort: 2 days.

Analytics Ingest

Low risk

Read-only API consumer. Only pagination logic changes. Can migrate independently. Estimated effort: 1 day.

Admin Dashboard

Low risk

Uses 3 endpoints with no breaking changes. SDK upgrade sufficient. Estimated effort: 0.5 days.

Risks

Key risks and mitigations for the remaining migration work.

Settlement callback downtime

Payment Core migration requires a maintenance window. If the webhook schema swap is not atomic, in-flight settlements may be lost. Mitigation: dual-write period of 24h before hard cutover.

Auth token propagation lag

Opaque tokens have a shorter TTL than JWTs. Services that cache tokens aggressively may see elevated 401 rates immediately after cutover. Mitigation: reduce cache TTL 48h before migration.

Error code mapping gaps

Three internal monitoring dashboards use hardcoded v1 error codes. These will need updates but do not affect service availability. Mitigation: update dashboards in parallel during migration week.

Next Actions

Recommended sequence to complete the migration safely.