bytelyst/learning_ai_invt_trdg
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
0c8d3cf912
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

6.6 KiB
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.