`QUICK_START.md`

356 lines
# Omega Watch API - Quick Start Guide

Get up and running with the Omega Watch Price History API in 5 minutes.

---

## 1. Explore the API (30 seconds)

**Interactive Documentation:**
http://45.61.58.125:7600/api/docs/swagger

Click "Try it out" on any endpoint to test it instantly in your browser.

---

## 2. Test with cURL (1 minute)

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

# Get all Speedmaster watches
curl "http://45.61.58.125:7600/api/watches?series=Speedmaster&limit=5"

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

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

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

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

---

## 3. Use JavaScript SDK (2 minutes)

### Install
```bash
# Copy SDK to your project
cp /root/Projects/watches/sdk/omega-api-client.js ./
```

### Use
```javascript
import OmegaWatchAPI from './omega-api-client.js';

const api = new OmegaWatchAPI();

// Get watches
const watches = await api.getWatches({
  series: 'Speedmaster',
  limit: 10
});
console.log(`Found ${watches.total} Speedmaster watches`);

// Search
const results = await api.search('moonwatch');
results.results.forEach(watch => {
  console.log(`${watch.model} - ${watch.series}`);
});

// Get statistics
const stats = await api.getStatistics();
console.log(`Average Appreciation: ${stats.averageAppreciation}%`);

// Get trending
const trending = await api.getTrending(5);
trending.trending.forEach(watch => {
  console.log(`${watch.model} - ${watch.views} views`);
});

// Compare watches
const comparison = await api.compareWatches([
  'speedmaster-moonwatch-1969',
  'seamaster-300-1957'
]);
console.log('Comparison:', comparison);

// WebSocket real-time updates
api.connectWebSocket({
  onUpdate: (data) => console.log('Price update:', data)
});
api.subscribeToWatch('speedmaster-moonwatch-1969');
```

---

## 4. Use Python SDK (2 minutes)

### Install
```bash
# Copy SDK to your project
cp /root/Projects/watches/sdk/omega_api_client.py ./
pip install requests
```

### Use
```python
from omega_api_client import OmegaWatchAPI

# Initialize
api = OmegaWatchAPI()

# Get watches
watches = api.get_watches(series='Speedmaster', limit=10)
print(f"Found {watches['total']} Speedmaster watches")

# Search
results = api.search('moonwatch')
for watch in results['results']:
    print(f"{watch['model']} - {watch['series']}")

# Get statistics
stats = api.get_statistics()
print(f"Average Appreciation: {stats['averageAppreciation']:.2f}%")

# Get trending
trending = api.get_trending(5)
for watch in trending['trending']:
    print(f"{watch['model']} - {watch['views']} views")

# Compare watches
comparison = api.compare_watches([
    'speedmaster-moonwatch-1969',
    'seamaster-300-1957'
])
print('Comparison:', comparison)

# Use context manager (automatic cleanup)
with OmegaWatchAPI() as api:
    health = api.get_health()
    print(f"API Status: {health['status']}")
```

---

## 5. Import to Postman (1 minute)

1. Download collection:
   ```bash
   curl -O http://45.61.58.125:7600/api/docs/openapi.json
   ```

2. Open Postman → Import → Upload Files

3. Select: `/root/Projects/watches/postman_collection.json`

4. Start testing all endpoints with pre-configured examples!

---

## Common Use Cases

### Get Top Performing Watches
```bash
curl http://45.61.58.125:7600/api/statistics | jq '.topPerformers'
```

```javascript
const stats = await api.getStatistics();
console.log('Top Performers:', stats.topPerformers);
```

```python
stats = api.get_statistics()
for watch in stats['topPerformers']:
    print(f"{watch['model']}: {watch['appreciation']:.2f}% appreciation")
```

### Search Vintage Watches
```bash
curl "http://45.61.58.125:7600/api/search?q=vintage&minYear=1940&maxYear=1970"
```

```javascript
const vintage = await api.search('vintage', {
  minYear: 1940,
  maxYear: 1970
});
```

```python
vintage = api.search('vintage', min_year=1940, max_year=1970)
```

### Get Investment Opportunities
```bash
curl http://45.61.58.125:7600/api/analytics/investment-opportunities
```

```javascript
const opportunities = await api.getInvestmentOpportunities();
```

```python
opportunities = api.get_investment_opportunities()
```

### Export All Data
```bash
# Export as JSON
curl http://45.61.58.125:7600/api/export/json -o watches.json

# Export as CSV
curl http://45.61.58.125:7600/api/export/csv -o watches.csv
```

```javascript
const jsonData = await api.exportData('json');
const csvData = await api.exportData('csv');
```

```python
json_data = api.export_data('json')
csv_data = api.export_data('csv')
```

---

## All Available Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/health` | GET | System health check |
| `/api/watches` | GET | Get all watches (with filters) |
| `/api/watches/{id}/history` | GET | Get watch price history |
| `/api/watches/trending` | GET | Get trending watches |
| `/api/search` | GET | Advanced search |
| `/api/price-predictions/{id}` | GET | AI price predictions |
| `/api/statistics` | GET | Market statistics |
| `/api/collections` | GET | Collection statistics |
| `/api/compare` | POST | Compare watches |
| `/api/export/{format}` | GET | Export data (json/csv) |
| `/api/watchlist` | POST | Manage watchlist |
| `/api/watchlist/{userId}` | GET | Get user watchlist |
| `/api/analytics/predictions` | GET | ML predictions |
| `/api/analytics/market` | GET | Market analysis |
| `/api/analytics/statistics` | GET | Statistical insights |
| `/api/analytics/investment-opportunities` | GET | Investment opportunities |
| `/api/analytics/risk-metrics` | GET | Risk metrics |
| `/api/admin/clear-cache` | POST | Clear cache (admin) |
| `/api/admin/backup` | GET | Create backup (admin) |

---

## Query Parameters

### GET /api/watches
- `series` - Filter by series (Speedmaster, Seamaster, etc.)
- `minYear` - Minimum year introduced
- `maxYear` - Maximum year introduced
- `minPrice` - Minimum current price (USD)
- `maxPrice` - Maximum current price (USD)
- `page` - Page number (default: 1)
- `limit` - Items per page (default: 50)

### GET /api/search
- `q` - Search query (required)
- `series` - Filter by series
- `movement` - Filter by movement type
- `minPrice` - Minimum price
- `maxPrice` - Maximum price
- `page` - Page number
- `limit` - Items per page

### GET /api/watches/trending
- `limit` - Number of results (default: 10)

---

## Response Format

All responses return JSON:

**Success:**
```json
{
  "total": 32,
  "page": 1,
  "limit": 10,
  "watches": [...]
}
```

**Error:**
```json
{
  "error": "Watch not found",
  "details": "No watch with ID: invalid-id"
}
```

---

## HTTP Status Codes

| Code | Description |
|------|-------------|
| 200 | Success |
| 400 | Bad Request - Invalid parameters |
| 404 | Not Found - Resource doesn't exist |
| 500 | Internal Server Error |

---

## WebSocket Example

```javascript
const ws = new WebSocket('ws://45.61.58.125:7600');

ws.onopen = () => {
  // Subscribe to watch updates
  ws.send(JSON.stringify({
    type: 'subscribe',
    watchId: 'speedmaster-moonwatch-1969'
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);

  if (data.type === 'subscribed') {
    console.log('Subscribed to:', data.watchId);
  }

  if (data.type === 'update') {
    console.log('Price update:', data.data);
  }
};
```

---

## Need More Help?

**Full Documentation:**
- Interactive Docs: http://45.61.58.125:7600/api/docs/swagger
- Complete Guide: `/root/Projects/watches/API_DOCUMENTATION.md`
- OpenAPI Spec: http://45.61.58.125:7600/api/docs/openapi.json

**Resources:**
- JavaScript SDK: `/root/Projects/watches/sdk/omega-api-client.js`
- Python SDK: `/root/Projects/watches/sdk/omega_api_client.py`
- Postman Collection: `/root/Projects/watches/postman_collection.json`

**Base URL:** http://45.61.58.125:7600

---

That's it! You're ready to start building with the Omega Watch API.