`docs/MIGRATION_GUIDE.md`

526 lines
# API Migration Guide

## Version History & Migration Paths

### Current Version: v2.0.0

This guide helps you migrate between API versions and understand breaking changes.

---

## Table of Contents

- [v1.0.0 to v2.0.0](#v100-to-v200)
- [Future: v2.x to v3.0.0](#v2x-to-v300-planned)
- [Deprecation Policy](#deprecation-policy)
- [Version Detection](#version-detection)

---

## v1.0.0 to v2.0.0

### Release Date: November 17, 2025

### Overview

**v2.0.0 is fully backward compatible with v1.0.0** - No breaking changes!

All existing v1.0.0 code will continue to work without modifications.

### What's New

#### 1. Enhanced Documentation

**Before (v1.0.0):**
```
Documentation available at /api/docs (basic HTML)
```

**After (v2.0.0):**
```
- Swagger UI:          /api/docs/swagger
- OpenAPI Spec:        /api/docs/openapi.json
- Interactive Playground: /api-playground.html
- Complete Guide:      /docs/API_COMPLETE_GUIDE.md
```

**Migration:** No changes needed. Old `/api/docs` redirects to Swagger UI.

---

#### 2. Official SDKs

**Before (v1.0.0):**
```javascript
// Manual fetch calls
const response = await fetch('http://45.61.58.125:7600/api/watches');
const data = await response.json();
```

**After (v2.0.0):**
```javascript
// Use official SDK
import OmegaWatchAPI from '@omega-watches/api-client';

const api = new OmegaWatchAPI();
const data = await api.getWatches();
```

**Migration:** Optional upgrade. Manual fetch calls still work.

---

#### 3. TypeScript Support

**Before (v1.0.0):**
```typescript
// No types available
const watches: any = await fetch(...).then(r => r.json());
```

**After (v2.0.0):**
```typescript
import OmegaWatchAPI, { Watch, WatchesListResponse } from '@omega-watches/api-client';

const api = new OmegaWatchAPI();
const watches: WatchesListResponse = await api.getWatches();
const watch: Watch = watches.watches[0];
```

**Migration:** Optional. Install `@omega-watches/api-client` for types.

---

#### 4. WebSocket Support

**Before (v1.0.0):**
```javascript
// Polling required
setInterval(async () => {
  const watch = await fetch(`/api/watches/${id}/history`).then(r => r.json());
  updateUI(watch);
}, 5000);
```

**After (v2.0.0):**
```javascript
// Real-time updates
const api = new OmegaWatchAPI();

api.connectWebSocket({
  onUpdate: (data) => updateUI(data)
});

api.subscribeToWatch(id);
```

**Migration:** Optional. Polling still works but WebSocket is more efficient.

---

#### 5. Enhanced Error Messages

**Before (v1.0.0):**
```json
{
  "error": "Not found"
}
```

**After (v2.0.0):**
```json
{
  "error": "Watch not found",
  "details": "Watch with ID 'invalid-id' does not exist. Use /api/watches to see available IDs."
}
```

**Migration:** Error handling code works the same. Errors now include `details` field.

---

#### 6. Response Caching Headers

**Before (v1.0.0):**
```
No cache headers
```

**After (v2.0.0):**
```
Cache-Control: public, max-age=300
ETag: "abc123"
Last-Modified: Mon, 17 Nov 2025 10:30:00 GMT
```

**Migration:** Automatic. Browsers will cache responses appropriately.

---

### New Endpoints in v2.0.0

These endpoints are new and have no v1.0.0 equivalent:

#### Interactive Playground
```
GET /api-playground.html
```

#### Enhanced Documentation
```
GET /api/docs/swagger
GET /api/docs/openapi.json
GET /api/docs/openapi.yaml
```

#### SDK Downloads
```
GET /sdk/omega-api-client.js
GET /sdk/omega_api_client.py
```

---

### No Breaking Changes

The following continue to work exactly as in v1.0.0:

- All `/api/*` endpoints
- Response format and structure
- Query parameters
- Request/response schemas
- Authentication (still optional)
- Export formats (JSON/CSV)

---

### Recommended Migration Steps

#### Step 1: Test Current Integration
```bash
# Ensure your v1.0.0 integration still works
curl http://45.61.58.125:7600/api/health
curl http://45.61.58.125:7600/api/watches?limit=5
```

#### Step 2: Review New Documentation
Visit the interactive playground:
```
http://45.61.58.125:7600/api-playground.html
```

#### Step 3: (Optional) Upgrade to SDK

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

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

#### Step 4: (Optional) Add TypeScript Types

```typescript
import OmegaWatchAPI, { Watch } from '@omega-watches/api-client';
```

#### Step 5: (Optional) Implement WebSocket

```javascript
const api = new OmegaWatchAPI();
api.connectWebSocket({ onUpdate: handleUpdate });
```

---

## v2.x to v3.0.0 (Planned)

### Expected: Q2 2026

### Breaking Changes (Planned)

#### 1. Authentication Required

**Current (v2.x):**
```bash
# Most endpoints are public
curl http://45.61.58.125:7600/api/watches
```

**Planned (v3.0):**
```bash
# API key required for all endpoints
curl -H "X-API-Key: your-key" \
  http://45.61.58.125:7600/api/watches
```

**Migration:**
1. Register for API key at `/auth/register`
2. Update all requests to include `X-API-Key` header
3. SDK will handle automatically: `new OmegaWatchAPI({ apiKey: 'your-key' })`

---

#### 2. Pagination Defaults

**Current (v2.x):**
```javascript
// Default limit: 50
await api.getWatches(); // Returns up to 50 watches
```

**Planned (v3.0):**
```javascript
// Default limit: 20
await api.getWatches(); // Returns up to 20 watches
await api.getWatches({ limit: 50 }); // Explicit limit required for 50
```

**Migration:**
Explicitly set `limit` parameter if you need more than 20 results.

---

#### 3. Date Format Standardization

**Current (v2.x):**
```json
{
  "lastUpdated": "2025-11-17T10:30:00.000Z"
}
```

**Planned (v3.0):**
```json
{
  "lastUpdated": "2025-11-17T10:30:00Z",
  "lastUpdatedUnix": 1700223000
}
```

**Migration:**
Update date parsing to handle ISO 8601 without milliseconds.

---

#### 4. Error Response Structure

**Current (v2.x):**
```json
{
  "error": "Error message",
  "details": "Additional info"
}
```

**Planned (v3.0):**
```json
{
  "error": {
    "code": "WATCH_NOT_FOUND",
    "message": "Error message",
    "details": "Additional info",
    "timestamp": "2025-11-17T10:30:00Z"
  }
}
```

**Migration:**
Update error handling to access `error.message` instead of `error`.

---

#### 5. GraphQL Support

**New in v3.0:**
```graphql
query {
  watches(series: "Speedmaster", limit: 10) {
    id
    model
    priceHistory {
      year
      price
    }
  }
}
```

**Migration:**
Optional. REST API will remain available.

---

### Deprecation Timeline (v3.0)

#### 6 Months Before v3.0 (December 2025)
- Deprecation warnings added to responses
- Migration guide published
- New API features available in beta

#### 3 Months Before v3.0 (March 2026)
- Deprecation notices in API docs
- Email notifications to registered users
- Migration assistance available

#### v3.0 Release (June 2026)
- Breaking changes take effect
- v2.x remains available at `/v2/api/*`
- v2.x maintained for 12 months

---

## Deprecation Policy

### Our Commitment

1. **6 Months Notice**: Minimum 6 months warning before breaking changes
2. **Version Support**: Previous major version supported for 12 months
3. **Migration Path**: Clear upgrade path and documentation
4. **Backward Compatibility**: Minor versions (2.1, 2.2) never break compatibility

### Deprecation Warnings

Deprecated features include warnings in responses:

```json
{
  "data": { ... },
  "warnings": [
    {
      "code": "DEPRECATED_FIELD",
      "message": "Field 'oldName' is deprecated. Use 'newName' instead.",
      "deprecatedIn": "2.1.0",
      "removedIn": "3.0.0"
    }
  ]
}
```

### Version Support Matrix

| Version | Released | Support Ends | Status |
|---------|----------|--------------|--------|
| v1.0.0 | Nov 2024 | Nov 2026 | Maintenance |
| v2.0.0 | Nov 2025 | Nov 2027 | Current |
| v3.0.0 | Jun 2026 | TBD | Planned |

---

## Version Detection

### Check Current Version

```bash
curl http://45.61.58.125:7600/api/health | jq '.version'
```

### Version Header

All responses include version header:

```
X-API-Version: 2.0.0
```

### SDK Version Check

```javascript
const api = new OmegaWatchAPI();
console.log(api.version); // "2.0.0"
```

---

## Migration Assistance

### Resources

- **Swagger UI**: http://45.61.58.125:7600/api/docs/swagger
- **Playground**: http://45.61.58.125:7600/api-playground.html
- **Complete Guide**: http://45.61.58.125:7600/docs/API_COMPLETE_GUIDE.md
- **Health Check**: http://45.61.58.125:7600/api/health

### Testing Your Migration

1. **Use Health Check**: Verify connectivity
   ```bash
   curl http://45.61.58.125:7600/api/health
   ```

2. **Test Key Endpoints**: Ensure expected responses
   ```bash
   curl http://45.61.58.125:7600/api/watches?limit=5
   ```

3. **Check Error Handling**: Verify error responses
   ```bash
   curl http://45.61.58.125:7600/api/watches/invalid-id/history
   ```

4. **Load Test**: Ensure performance
   ```bash
   ab -n 100 -c 10 http://45.61.58.125:7600/api/statistics
   ```

---

## Changelog Summary

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

**New Features:**
- Interactive Swagger UI documentation
- Complete OpenAPI 3.0.3 specification
- JavaScript/TypeScript SDK with full type definitions
- Python client library
- WebSocket support for real-time updates
- Interactive API playground
- Enhanced error messages with details
- Response caching headers
- Postman collection v2.1

**Improvements:**
- Better documentation organization
- Improved example code
- Enhanced SDK error handling
- TypeScript support
- Performance optimizations

**Bug Fixes:**
- None (no bugs in v1.0.0)

**Breaking Changes:**
- None (fully backward compatible)

---

### v1.0.0 (2024-11-17)

**Initial Release:**
- REST API for watch data
- Price history endpoints
- Search functionality
- Analytics and predictions
- Collections API
- JSON/CSV export
- Basic documentation

---

## Questions?

For migration questions or issues:

1. Check the health endpoint: http://45.61.58.125:7600/api/health
2. Review the complete guide: http://45.61.58.125:7600/docs/API_COMPLETE_GUIDE.md
3. Test in the playground: http://45.61.58.125:7600/api-playground.html

---

**Last Updated:** 2025-11-17
**Current Version:** 2.0.0