Versioned API Adapters for Incremental Migration

An API rewrite is easy to draw and risky to deploy. The safer path is to define the target resource contract, keep current endpoints working, and move one vertical feature at a time behind adapters.

Version behavior, not folder names

Adding /v1 is useful only if request validation, identifiers, timestamps, error codes, and idempotency are stable. The target contract uses UUID-like IDs, UTC storage, Seoul-local date calculation, and explicit ownership and visibility. Existing endpoints can map their compact payloads to that model without duplicating data.

Move by vertical slice

The first slice included recommendation reasons, a five-item daily capacity limit, timer recovery, and session writes. The next slice added weekly plan generation and locking. Each step kept the existing study tabs and database available. This produces a smaller rollback surface than replacing the whole dashboard.

An adapter should be temporary but observable. It needs contract tests on both sides and a retirement condition: all callers migrated, equivalent persistence verified, and no old traffic during a measured window.

External APIs need the same boundary

The distribution code follows the same rule. A LinkedIn adapter validates a local kit and produces a request only when explicit credentials and --apply are present. The API version is a header, not a hidden constant, so sunset migration does not require rewriting content logic. Without permission, preflight performs no network write.

Adapters are not an excuse to keep two permanent systems. Their value is to preserve service while evidence accumulates for a controlled cutover.