Write an API reference covering every endpoint, status code, and error code

[mikewheeleer]

Write a complete API reference

Description

README.md documents only the deep readiness probe and the generic error shape. The bulk of the surface in src/index.ts — pairs CRUD and per-pair meta PATCH endpoints, single and bulk quotes, api-keys, webhooks, admin pause/status, stats, metrics, events, and config — is undocumented outside the terse GET /api/v1/openapi.json literal. New contributors have no human-readable map of the API. This issue adds a full API reference document.

Requirements and context

• Repository scope: StableRoute-Org/Stableroute-backend only.
• Create docs/api.md (create file) documenting every route: method, path, query/path/body params, success response shape and status, and the error codes it can emit (invalid_request, not_found, payload_too_large, rate_limited, service_paused, internal_error).
• Document the canonical { error, message, requestId } envelope and the X-Request-Id correlation header once, then reference it per-endpoint.
• Include concrete curl examples for the common flows: register a pair, set fee/min/max/liquidity, get a quote, create an api-key, register a webhook.
• Link docs/api.md from README.md.

Suggested execution

• Fork the repo and create a branch
• git checkout -b docs/api-reference-38-full-reference
• Implement changes
  • Write code in: documentation only — create docs/api.md and link it from README.md.
  • Write comprehensive tests in: not applicable (docs-only).
  • Add documentation: this issue is the documentation.
  • Keep examples consistent with the actual request/response shapes in src/index.ts.
  • Validate security: ensure examples never show real keys; document the auth-related error codes accurately.
• Test and commit

Test and commit

• Run npm run build, npm run lint, and npm test to confirm the repo still builds.
• Cover edge cases: verify each documented status code and error string matches the handlers in src/index.ts.
• Paste a short table of contents from docs/api.md in the PR.

Example commit message

docs(api-reference): add a complete endpoint and error-code reference

Guidelines

• Minimum 95 percent test coverage for impacted code (where any code is touched).
• Clear, reviewer-focused documentation.
• Timeframe: 96 hours.

Community & contribution rewards

• 💬 Join the StableRoute community on Discord for questions, reviews, and faster merges: https://discord.gg/37aCpusvx
• ⭐ This is a GrantFox OSS / Official Campaign task and may be rewarded. When your PR is merged you'll be prompted to rate the project — if this issue and the maintainers helped you ship, we'd be grateful for a 5-star rating. Clear questions in Discord and tidy, well-tested PRs are the fastest path to a merge and a reward.

[Jagadeeshftw]

Hi, I’d love to take on this issue! With my expertise in Rust, Stellar, and smart contract development, I can implement a clean and efficient solution.

🚀 Why Me?

• Proven Blockchain Experience – Hands-on work with Stellar, Solidity, and Rust, building secure and optimized smart contracts.
• Open Source Contributor – Actively contributed to 50+ open-source projects, showcasing adaptability and collaboration.
• Efficient & Reliable – I deliver high-quality, production-ready solutions quickly, ensuring security and scalability.

⏱ Timeline

I estimate completing this within 24 hours. Let me know if I can proceed!

[grantfox-oss]

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

Next steps:

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

Good luck! Track your progress on GrantFox.