testnet: freeze the v1 API surface and document the compatibility promise

[Depo-dev]

Once SDKs ship against testnet, breaking changes cost other people work. Right now there is no stated promise about what v1 guarantees.

Scope

• Declare what is stable in v1: routes, request/response shapes, error codes, pagination semantics.
• Declare what is explicitly not stable yet.
• Define the deprecation policy: notice period, and how removal is signalled.
• Decide how a breaking change would be versioned if one becomes unavoidable.

Done when

• The compatibility promise is documented and the v1 surface is frozen against it.

[sagesan2580]

@sagesan2580 has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Hello maintainer please can I be assigned to this issue? ETA <= 48hrs

ℹ️ Repo Maintainers: To accept this application, review their application or assign @sagesan2580 to this issue.

[akinolavictor419-sketch]

@akinolavictor419-sketch has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

I will love to fix this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @akinolavictor419-sketch to this issue.

[Miracle656]

@Miracle656 has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

I’d like to claim this issue. Formalizing our v1 API compatibility promise and freezing the public surface is essential to give downstream SDK authors and developers stable integration guarantees on testnet.

My implementation plan:

Audit & Freeze Stable v1 Surface: Document all stable public contracts in docs/api/v1-compatibility.md—including REST/RPC routes, schema structures, error code payloads (code, message, details), and cursor-based pagination semantics (cursor, limit, order).

Explicitly Scoped Non-Guarantees: Clearly carve out surfaces that remain experimental or subject to evolution (e.g., internal debug routes, unstable websocket streams, or raw unindexed XDR metadata fields).

Deprecation & Sunset Protocol: Define a concrete deprecation policy requiring at least 30 days notice on testnet (and 90 days on mainnet), signaled via standard HTTP response headers (Deprecation: true, Sunset: , and Link: ; rel="sunset").

Versioning & Evolution Policy: Document how unavoidable breaking changes must be introduced—via path-based major version increments (/api/v2) or additive non-breaking fields, ensuring /v1 endpoints remain functional throughout the transition period.

Please assign this to me!

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Miracle656 to this issue.

[drips-wave]

Congratulations, @Miracle656! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on August 31, 2026.

🧑‍💻 @Miracle656: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊