`docs/README.md`

324 lines
# Omega Watch Price History API - Documentation Hub

Welcome to the complete documentation for the Omega Watch Price History API.

## Quick Links

### Interactive Tools
- **API Playground** - Test endpoints in your browser: http://45.61.58.125:7600/api-playground.html
- **Swagger UI** - Interactive API documentation: http://45.61.58.125:7600/api/docs/swagger
- **OpenAPI Spec** - Machine-readable specification: http://45.61.58.125:7600/api/docs/openapi.json

### Documentation
- **[Complete Developer Guide](./API_COMPLETE_GUIDE.md)** - Full API reference with examples
- **[Migration Guide](./MIGRATION_GUIDE.md)** - Version history and upgrade paths
- **[Postman Collection](http://45.61.58.125:7600/postman_collection.json)** - Import into Postman

### SDKs & Client Libraries
- **JavaScript/TypeScript** - http://45.61.58.125:7600/sdk/omega-api-client.js
- **Python** - http://45.61.58.125:7600/sdk/omega_api_client.py

---

## Documentation Structure

```
docs/
├── README.md                    # This file
├── API_COMPLETE_GUIDE.md        # Complete API documentation
├── MIGRATION_GUIDE.md           # Version migration guide
└── examples/                    # Code examples (planned)
    ├── javascript/
    ├── python/
    └── curl/
```

---

## Getting Started

### 1. Test the API

```bash
# Check system health
curl http://45.61.58.125:7600/api/health

# Get watches
curl http://45.61.58.125:7600/api/watches?limit=5

# Search
curl "http://45.61.58.125:7600/api/search?q=moonwatch"
```

### 2. Install SDK

**JavaScript/Node.js:**
```bash
npm install @omega-watches/api-client
```

**Python:**
```bash
pip install omega-watch-api
```

### 3. Start Building

**JavaScript:**
```javascript
import OmegaWatchAPI from '@omega-watches/api-client';

const api = new OmegaWatchAPI();
const watches = await api.getWatches({ series: 'Speedmaster' });
console.log(`Found ${watches.total} watches`);
```

**Python:**
```python
from omega_api_client import OmegaWatchAPI

api = OmegaWatchAPI()
watches = api.get_watches(series='Speedmaster')
print(f"Found {watches['total']} watches")
```

---

## API Overview

### Base URL
```
http://45.61.58.125:7600
```

### Authentication
Most endpoints are public. Admin endpoints require `X-API-Key` header.

### Response Format
All responses are JSON (except CSV export).

### Rate Limiting
No rate limiting currently. Fair usage expected.

---

## Key Endpoints

### Health & System
- `GET /api/health` - System health status

### Watches
- `GET /api/watches` - List all watches with filtering
- `GET /api/watches/{id}/history` - Get price history
- `GET /api/watches/trending` - Most viewed watches

### Search
- `GET /api/search` - Advanced search with filters

### Analytics
- `GET /api/price-predictions/{id}` - AI price predictions
- `GET /api/statistics` - Market statistics

### Collections
- `GET /api/collections` - All collections with stats

### Comparison
- `POST /api/compare` - Compare multiple watches

### Export
- `GET /api/export/json` - Export as JSON
- `GET /api/export/csv` - Export as CSV

---

## Code Examples

### Get Top Performing Watches

```javascript
const api = new OmegaWatchAPI();
const stats = await api.getStatistics();

console.log('Top 5 Performers:');
stats.topPerformers.slice(0, 5).forEach((watch, i) => {
  console.log(`${i+1}. ${watch.model}`);
  console.log(`   Appreciation: ${watch.appreciation.toFixed(2)}%`);
});
```

### Calculate ROI

```python
api = OmegaWatchAPI()

watch = api.get_watch_by_id('speedmaster-moonwatch-1969')
history = watch['priceHistory']

original = history[0]['price']
current = history[-1]['price']
roi = ((current - original) / original) * 100

print(f"ROI: {roi:.2f}%")
```

### Real-time Price Monitoring

```javascript
const api = new OmegaWatchAPI();

api.connectWebSocket({
  onUpdate: (data) => {
    console.log(`${data.watchId}: $${data.data.price}`);
  }
});

api.subscribeToWatch('speedmaster-moonwatch-1969');
```

---

## Documentation Versions

| Version | Date | Status | Documentation |
|---------|------|--------|---------------|
| 2.0.0 | 2025-11-17 | Current | This version |
| 1.0.0 | 2024-11-17 | Supported | Legacy docs |

See [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md) for upgrade information.

---

## API Features

### Core Features
- 32+ Omega watches tracked
- Historical price data from 1940s to present
- 9 watch collections (Speedmaster, Seamaster, etc.)
- AI-powered price predictions
- Real-time analytics

### Developer Features
- Complete OpenAPI 3.0.3 specification
- Official JavaScript/TypeScript SDK
- Official Python client
- WebSocket support for real-time updates
- Interactive API playground
- Postman collection
- Comprehensive error messages
- Response caching

### Data Features
- JSON/CSV export
- Price history tracking
- Investment analytics
- Collection statistics
- Trend analysis
- Watch comparisons

---

## Common Use Cases

### 1. Price Tracking Dashboard
Build a dashboard to track watch prices over time.

### 2. Investment Portfolio Manager
Calculate ROI and track your watch investments.

### 3. Market Analysis Tool
Analyze market trends and identify opportunities.

### 4. Price Alert System
Get notified when watches hit target prices.

### 5. Collection Browser
Browse and compare different Omega collections.

---

## Testing

### Test with cURL

```bash
# Health check
curl http://45.61.58.125:7600/api/health

# Get all watches
curl http://45.61.58.125:7600/api/watches?limit=10

# Search
curl "http://45.61.58.125:7600/api/search?q=speedmaster"

# Get predictions
curl http://45.61.58.125:7600/api/price-predictions/speedmaster-moonwatch-1969

# Get statistics
curl http://45.61.58.125:7600/api/statistics
```

### Test with Postman

1. Download collection: http://45.61.58.125:7600/postman_collection.json
2. Import into Postman
3. Set environment variable: `baseUrl = http://45.61.58.125:7600`
4. Run collection

### Test in Browser

Visit the interactive playground:
http://45.61.58.125:7600/api-playground.html

---

## Support & Resources

### Documentation
- Complete Guide: [API_COMPLETE_GUIDE.md](./API_COMPLETE_GUIDE.md)
- Migration Guide: [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md)
- OpenAPI Spec: http://45.61.58.125:7600/api/docs/openapi.json

### Interactive Tools
- Swagger UI: http://45.61.58.125:7600/api/docs/swagger
- API Playground: http://45.61.58.125:7600/api-playground.html

### Health & Status
- Health Check: http://45.61.58.125:7600/api/health
- Server Status: Check `/api/health` for uptime and performance metrics

---

## License

MIT License - see LICENSE file for details

---

## Changelog

### v2.0.0 (2025-11-17)

**New:**
- Interactive API playground
- Complete OpenAPI 3.0.3 spec
- JavaScript/TypeScript SDK with types
- Python client library
- WebSocket real-time updates
- Enhanced documentation
- Migration guide

**Improvements:**
- Better error messages
- Response caching
- Performance optimization
- SDK error handling

**No Breaking Changes**
- Fully backward compatible with v1.0.0

---

**Last Updated:** 2025-11-17
**API Version:** 2.0.0
**Documentation Version:** 2.0.0