Backend: API has no versioning prefix — breaking changes have no deprecation path

[k-deejah]

Difficulty: Advanced

Problem

1. All backend routes are mounted at /api/queues, /api/enrollments, /api/escrow with no version segment
backend/src/index.ts lines 28–32: routes are mounted directly without a /v1 or any version prefix. Any breaking change to request/response schemas (adding a required field, renaming a field, changing a response status code) immediately breaks all existing API consumers with no grace period.

2. No Accept header versioning, no Api-Version header — no alternative versioning mechanism
There is no middleware that reads Accept: application/vnd.lineproof.v1+json or X-Api-Version: 1 headers. The only way to version a breaking change is to change the URL, which is not currently supported.

3. No deprecation headers or documentation for the current /api/ path
When versioned routes (/api/v1/) are eventually added, there needs to be a mechanism to signal that /api/ is deprecated. The Deprecation and Sunset HTTP headers (RFC 8594) are the standard mechanism but are not implemented anywhere.

Impact: The backend API has no evolution path. The first breaking change (which will come when Soroban integration lands and response shapes change) will silently break all existing clients including the frontend, SDK integration tests, and any operator tooling.

Proposed Solution

• Mount all routes under /api/v1/: app.use('/api/v1/queues', queueRoutes).
• Create a backward-compat middleware that proxies /api/queues → /api/v1/queues with a Deprecation: true and Sunset: <date> header.
• Document the versioning policy in docs/api-reference/versioning.md.
• Update frontend hooks to use /api/v1/ prefix (or keep the proxy transparent).

Acceptance Criteria

• All routes accessible at both /api/v1/queues (primary) and /api/queues (deprecated)
• Requests to /api/ routes return Deprecation: true header
• Sunset header set to a date 6 months in the future
• docs/api-reference/versioning.md created with versioning policy
• Frontend hooks updated to use /api/v1/ (or proxy is transparent)
• All existing tests updated to use /api/v1/ paths

Contributor Note

If assigned, your PR must explain the URL-prefix vs Accept-header versioning trade-off and justify which approach is used. Include the Sunset date for the legacy /api/ routes.

[Chigybillionz]

Hi, I’ve reviewed this issue and I’m confident I can fix it. I’d like to take it on.

[Chucks1093]

I’d like to work on this because I’m interested in designing APIs that can evolve without breaking existing clients, and I can implement the versioned routes, backward compatibility layer, deprecation headers, documentation, and test updates.

[grantfox-oss]

🦊 GrantFox — @Chucks1093 has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #207)
2. Your PR will be reviewed by the Stellar-Deejah maintainers

Good luck! Track your progress on GrantFox.