Create REST API for external integrations

[AbdelStark]

Description

Develop a comprehensive REST API to enable third-party integrations, mobile app development, and programmatic access to Markstr prediction markets.

API Endpoints to Implement

Market Management

• GET /api/v1/markets - List all markets with filtering/pagination
• GET /api/v1/markets/{id} - Get specific market details
• POST /api/v1/markets - Create new market (authenticated)
• PUT /api/v1/markets/{id} - Update market details (authorized users only)
• DELETE /api/v1/markets/{id} - Cancel market (authorized users only)

Betting Operations

• POST /api/v1/markets/{id}/bets - Place a bet
• GET /api/v1/markets/{id}/bets - List market bets
• GET /api/v1/users/{id}/bets - Get user's betting history
• GET /api/v1/markets/{id}/odds - Get current market odds

Oracle Management

• GET /api/v1/oracles - List available oracles
• GET /api/v1/oracles/{id} - Get oracle details and reputation
• POST /api/v1/oracles/{id}/settle - Settle market (oracle only)
• GET /api/v1/oracles/{id}/markets - Get oracle's markets

Analytics & Stats

• GET /api/v1/stats/platform - Platform-wide statistics
• GET /api/v1/stats/markets/{id} - Market-specific analytics
• GET /api/v1/stats/users/{id} - User statistics and performance

Technical Requirements

• RESTful design following OpenAPI 3.0 specification
• JSON request/response format with proper content types
• Rate limiting and throttling (e.g., 1000 requests/hour per IP)
• API key authentication for programmatic access
• JWT tokens for user session management
• CORS support for browser-based integrations
• Input validation and sanitization
• Comprehensive error handling with meaningful HTTP status codes
• API versioning strategy (/api/v1, /api/v2, etc.)

Documentation & Tooling

• Auto-generated OpenAPI/Swagger documentation
• Interactive API explorer interface
• SDK generation for popular languages (Python, JavaScript, Go)
• Code examples and integration guides
• Postman/Insomnia collection for testing
• API changelog and versioning documentation

Security & Performance

• Request/response logging for debugging
• API monitoring and health checks
• Database query optimization for endpoints
• Caching layer for frequently accessed data
• Security headers and best practices
• Input validation against injection attacks

Acceptance Criteria

• All CRUD operations work correctly via API
• API documentation is comprehensive and up-to-date
• Rate limiting prevents abuse while allowing legitimate usage
• Authentication and authorization work securely
• API responses are fast (<200ms for simple queries)
• Third-party developers can easily integrate with the platform