docs: add API v1 to v2 migration guide (#276) - #346
Open
i-amdaveee wants to merge 1 commit into
Open
Conversation
Add docs/API_V1_TO_V2_MIGRATION.md — a client-facing guide for moving from
v1 (current stable) to v2. Documents all planned breaking changes with
before/after examples, a phased migration checklist, and a deprecation
timeline anchored to v2 GA.
v1 examples reflect the real current responses (deposit shape and the
{data, pagination} list envelope from transactionController.ts). v2 is
mounted at /api/v2 but currently returns 501, so the guide is written as
forward-looking (prepare now, adopt at beta) and v2 payloads are marked
provisional until the beta contract is frozen.
Linked from the existing API_VERSIONING.md summary section.
|
@i-amdaveee Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits. You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
closes #276
Add API Migration Guide from v1 to v2 (#276)
Adds
docs/API_V1_TO_V2_MIGRATION.md— a client-facing guide for moving from the current stable v1 API to v2. Linked from the existingAPI_VERSIONING.mdsummary section.Context: v2 is not yet shipped
The v2 routes are mounted at
/api/v2/*but every handler currently returns501 Not Implemented("V2 API is coming soon"). The breaking changes exist as scaffolding and route-stub comments (src/routes/v2/,src/middleware/apiVersion.ts), not as live behavior.So this guide is deliberately forward-looking: clients do the prepare ralize response parsing) and the adapt/cut-over steps when the beta ships.v1 examples are the real current responses; v2 payloads are marked provisional until the beta contract is frozen.
What's included
unwrap()parser that handles both v1 and v2 during transitioAPI_VERSIONING.md### Acceptance criteria
- [x] Guide covers all breaking changes
Reviewer notes
Two pre-existing inconsistencies in
API_VERSIONING.mdsurfaced while writiut out of scope for this docs PR:/api/versionreturns"supported": ["v1"], but the middlewar["v1", "v2"]. My guide shows["v1", "v2"]` to match the code./api/versionanywhere insrc/— the endpoint may not actually be wired up.Docs-only change; no code touched.