bytelyst/learning_ai_invt_trdg
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
74400fda70
learning_ai_invt_trdg/docs/BACKEND_API_DEPRECATION.md
Saravana Achu Mac d955d00c00 feat(contracts): shared socket namespaces, tab flags, cutover docs, README 
- shared/realtime.ts: add SOCKET_NAMESPACES constants (/trading, /admin, root)
- shared/feature-flags.ts: add tabs.marketplace and tabs.membership to
  TradingFeatureFlagsResponse; add FEATURE_FLAG_KEYS constants
- .env.example: remove /api suffix from VITE/NEXT_PUBLIC trading URL vars
  (web appends /api itself); add tab visibility flag vars with comments
- web: add useTabFeatureFlags hook + DOM test; wire tab visibility into App.tsx
- web/vite.config.ts: finalize build config
- mobile/providers/TradingDataProvider.tsx: deriveSocketParams for proxy-safe
  socket origin/path resolution (already landed upstream, conflict resolved)
- docs: add CUTOVER_WEB.md, CUTOVER_MOBILE.md checklists; update OPERATIONS.md
  with Docker commands and resolved gap log; update ROADMAP.md to Done;
  add BACKEND_AUDIT_SCHEMA.md, BACKEND_API_DEPRECATION.md, CONVENTIONS.md;
  add audit-events container entry to AZURE_INFRASTRUCTURE.md
- README.md: full rewrite with workspace table, arch summary, env var reference

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-29 19:35:53 -04:00

164 lines
6.6 KiB
Markdown
Raw Blame History

# Backend API — Deprecation and Legacy Compatibility
## Purpose
This document tracks the lifecycle status of all backend API endpoints:
which endpoints are current, which are transitional, and which have been
superseded or are candidates for removal.
---
## Current API Surface
All endpoints require Bearer token authentication (`requireAuth`) unless marked Public.
Admin endpoints additionally require `requireAdmin`.
### Health & Observability (Public)
| Method | Path | Status | Notes |
|---|---|---|---|
| GET | `/health` | Current | Basic liveness — returns uptime + loop health |
| GET | `/health/live` | Current | Kubernetes-style liveness probe |
| GET | `/health/ready` | Current | Kubernetes-style readiness probe |
| GET | `/internal/health` | Current | Internal full health dump (not auth-gated; firewall-restrict in prod) |
| GET | `/metrics` | Current | Prometheus metrics via `prom-client` |
### Trading State
| Method | Path | Status | Notes |
|---|---|---|---|
| GET | `/api/state` | Current | Full BotState snapshot for authenticated user |
| GET | `/api/lifecycle/canonical` | Current | Canonical lifecycle event log for a trade |
| GET | `/api/alerts` | Current | Recent alert list |
| GET | `/api/symbol/:symbol` | Current | Per-symbol signal and indicator state |
### Trading Controls (Admin)
| Method | Path | Status | Notes |
|---|---|---|---|
| GET | `/internal/trading/status` | Current | Current trading control mode |
| POST | `/internal/trading/pause` | Current | Pause all new trade entries (admin only) |
| POST | `/internal/trading/resume` | Current | Resume trading (admin only) |
| POST | `/api/admin/revert-backfill-batch` | Current | Revert an exit backfill batch (admin only) |
### Config & Feature Flags
| Method | Path | Status | Notes |
|---|---|---|---|
| GET | `/api/config` | Current | Current runtime config subset (public fields only) |
| GET | `/api/feature-flags` | Current | Authoritative feature-flag contract (backtest, tabs) |
| GET | `/api/admin/config/dynamic` | Current | Full dynamic config (admin only) |
| PUT | `/api/admin/config/dynamic` | Current | Update dynamic config entries (admin only) |
### User Profile & Identity
| Method | Path | Status | Notes |
|---|---|---|---|
| GET | `/api/me/profile` | Current | Authenticated user's platform profile |
| PATCH | `/api/me/profile` | Current | Update user profile fields |
### Trading Profiles (Strategies)
| Method | Path | Status | Notes |
|---|---|---|---|
| GET | `/api/profiles` | Current | List trading profiles for authenticated user |
| POST | `/api/profiles` | Current | Create a new trading profile |
| PUT | `/api/profiles/:id` | Current | Replace a trading profile |
| PATCH | `/api/profiles/:id/active` | Current | Toggle profile active/inactive |
| DELETE | `/api/profiles/:id` | Current | Delete a trading profile |
### Orders & Positions
| Method | Path | Status | Notes |
|---|---|---|---|
| GET | `/api/positions/bootstrap` | Current | Initial position state for dashboard bootstrap |
| GET | `/api/trade-history` | Current | Closed trade history for authenticated user |
| GET | `/api/manual-entries` | Current | Manual trade entries for authenticated user |
| POST | `/api/manual-entries` | Current | Create a manual trade entry |
| PUT | `/api/manual-entries/:id` | Current | Update a manual trade entry |
| DELETE | `/api/manual-entries/:id` | Current | Delete a manual trade entry |
| POST | `/api/trade` | Current | Submit a live trade action (entry/exit signal) |
| POST | `/api/close` | Current | Close a position |
### Marketplace
| Method | Path | Status | Notes |
|---|---|---|---|
| GET | `/api/marketplace-presets` | Current | List publicly available strategy presets |
| POST | `/api/marketplace-presets` | Current | Create a marketplace preset (admin only) |
### Backtest
| Method | Path | Status | Notes |
|---|---|---|---|
| POST | `/api/backtest/run` | Current | Run a backtest (gated by `ENABLE_BACKTEST` flag) |
### AI & Diagnostics
| Method | Path | Status | Notes |
|---|---|---|---|
| GET | `/api/ai/health` | Current | AI provider health and fallback chain status |
| POST | `/api/chat` | Current | AI strategy assistant chat endpoint |
### Events & Reconciliation (Admin)
| Method | Path | Status | Notes |
|---|---|---|---|
| DELETE | `/api/events` | Current | Clear operational event log (admin only) |
| GET | `/api/admin/audit` | Current | Trade audit event log — requires `audit-events` Cosmos container (admin only) |
| GET | `/api/reconciliation/backfill/audit` | Current | Backfill audit records (admin only) |
| GET | `/api/reconciliation/backfill/batches` | Current | Backfill batch summary (admin only) |
---
## Transitional / Internal-Only Endpoints
| Path | Notes |
|---|---|
| `/internal/health` | Not auth-gated. Must be firewall-restricted in production. Not for external clients. |
| `/internal/trading/status` | `/internal/` prefix signals operator tooling only. Not part of the public client API contract. |
| `/internal/trading/pause` | Same as above. |
| `/internal/trading/resume` | Same as above. |
---
## Deprecated Endpoints
There are no formally deprecated endpoints in the current monorepo runtime.
Legacy Supabase-backed API variants (direct browser-side table reads) existed in the old
`bytelyst-trading-dashboard-web` repo and were replaced with backend API calls during
Phase 3 migration. Those call paths no longer exist in this codebase.
---
## Planned Additions (Not Yet Implemented)
| Endpoint | Status | Notes |
|---|---|---|
| `GET /api/admin/audit` | Implemented | Queries Cosmos `audit-events` container — activate by creating the container (see docs/BACKEND_AUDIT_SCHEMA.md) |
| `GET /api/push/register` | Planned | Register mobile push token — blocked on push provider selection |
| `DELETE /api/push/register` | Planned | Deregister mobile push token — blocked on push provider selection |
---
## Versioning Policy
- No API version prefix (`/v1/`) is currently in use. All endpoints are implicitly v1.
- Breaking changes require a deprecation notice in this document and a migration period
of at least one full deploy cycle before removal.
- The `x-request-id` header is the primary correlation key for client/backend tracing.
---
## WebSocket Namespaces
| Namespace | Purpose | Auth |
|---|---|---|
| `/` (root) | Backward-compatible default; all authenticated users | Bearer token required |
| `/trading` | Named user-facing namespace; receives user-scoped BotState | Bearer token required |
| `/admin` | Admin-only namespace; receives full cross-user state | Bearer token + admin role required |
Web and mobile clients connect to `/trading` by default.
The root namespace is retained for backward compatibility.
Reference in New Issue View Git Blame Copy Permalink