# API Versioning Implementation Guide

## Overview

This document describes the API versioning implementation for the Bookrah booking platform. The API now supports versioning while maintaining full backward compatibility with existing clients.

## ✅ Implementation Status: **COMPLETE**

---

## API Structure

### URL Patterns

```
Main API:        /api/v1/{endpoint}
Business API:    /api/business/v1/{endpoint}
Admin API:       /api/admin/v1/{endpoint}
Legacy Routes:   /api/{endpoint} (maintained for backward compatibility)
```

### Version Information Endpoint

```bash
GET /api
GET /api/version
```

**Response:**
```json
{
  "name": "Bookrah Booking API",
  "version": "1.0.0",
  "latest_version": "v1",
  "status": "active",
  "documentation": {
    "base_url": "https://bookrah.test/api",
    "v1": "https://bookrah.test/api/v1",
    "business_v1": "https://bookrah.test/api/business/v1",
    "admin_v1": "https://bookrah.test/api/admin/v1"
  }
}
```

---

## Available Endpoints

### 📘 **Main API (v1)**

#### Authentication
```
POST   /api/v1/login
POST   /api/v1/register
POST   /api/v1/google/login
POST   /api/v1/logout
GET    /api/v1/me
POST   /api/v1/forget-password
POST   /api/v1/verify-otp-password
POST   /api/v1/reset-password
POST   /api/v1/resend-otp
```

#### User Management
```
POST   /api/v1/profile/complete
POST   /api/v1/update/user
POST   /api/v1/password/change
DELETE /api/v1/delete/user
```

#### Notifications
```
GET    /api/v1/my-notifications
POST   /api/v1/notifications/{id}/mark-read
POST   /api/v1/notifications/mark-all-read
DELETE /api/v1/notifications/{id}
GET    /api/v1/notifications/unread-count
```

#### General Data
```
GET    /api/v1/settings
GET    /api/v1/city
GET    /api/v1/categories
GET    /api/v1/hero
GET    /api/v1/testimonials
GET    /api/v1/dynamic-pages
GET    /api/v1/dynamic-page/{slug}
```

#### Search
```
GET    /api/v1/search
GET    /api/v1/search/trending
```

#### Companies
```
GET    /api/v1/company/{slug}
```

#### Bookings
```
GET    /api/v1/booking/company/{slug}
GET    /api/v1/booking/company/{slug}/profeshionals
POST   /api/v1/booking/availability/check
```

#### Subscriptions
```
GET    /api/v1/subscriptions
GET    /api/v1/subscriptions/featured
GET    /api/v1/subscriptions/duration/{duration}
GET    /api/v1/subscriptions/{id}
```

#### Authenticated Booking Management
```
POST   /api/v1/bookings
GET    /api/v1/bookings/my
GET    /api/v1/bookings/{id}
POST   /api/v1/bookings/{id}/cancel
PUT    /api/v1/bookings/{id}/status
GET    /api/v1/bookings/business/all
```

#### Reviews
```
GET    /api/v1/reviews
POST   /api/v1/reviews
GET    /api/v1/reviews/{id}
PUT    /api/v1/reviews/{id}
DELETE /api/v1/reviews/{id}
```

---

### 🏢 **Business API (v1)**

#### Dashboard
```
GET    /api/business/v1/dashboard
```

#### Bookings & Calendar
```
GET    /api/business/v1/bookings/calendar
GET    /api/business/v1/bookings/date
```

#### Clients
```
GET    /api/business/v1/clients
GET    /api/business/v1/clients/{id}
```

#### Services
```
GET    /api/business/v1/services
POST   /api/business/v1/services
GET    /api/business/v1/services/{slug}
PUT    /api/business/v1/services/{slug}
DELETE /api/business/v1/services/{slug}
GET    /api/business/v1/services/category/{category_id}
```

#### Categories
```
GET    /api/business/v1/categories
GET    /api/business/v1/category/services
```

#### Employees
```
GET    /api/business/v1/employees
POST   /api/business/v1/employees
POST   /api/business/v1/employees/address
POST   /api/business/v1/employees/contact
POST   /api/business/v1/employees/set/services
POST   /api/business/v1/employees/update/{id}
DELETE /api/business/v1/employees/{id}
```

#### Employee Shifting
```
GET    /api/business/v1/employees/shifting/{employee}
POST   /api/business/v1/employees/shifting/{employee}
GET    /api/business/v1/employees/shifting/change/{employee}
```

#### Company Settings
```
GET    /api/business/v1/bio-gallery
POST   /api/business/v1/bio-gallery
DELETE /api/business/v1/bio-gallery/{id}
GET    /api/business/v1/company/shifting
POST   /api/business/v1/company/shifting
```

#### Account & Addresses
```
POST   /api/business/v1/account/complete
GET    /api/business/v1/addresses
POST   /api/business/v1/addresses
PUT    /api/business/v1/addresses/{id}
DELETE /api/business/v1/addresses/{id}
```

---

### 🔧 **Admin API (v1)**

#### Dashboard
```
GET    /api/admin/v1/bookings/dashboard
```

#### Booking Management
```
GET    /api/admin/v1/bookings
GET    /api/admin/v1/bookings/{id}
PUT    /api/admin/v1/bookings/{id}
DELETE /api/admin/v1/bookings/{id}
```

#### Booking Actions
```
POST   /api/admin/v1/bookings/{id}/flag
POST   /api/admin/v1/bookings/{id}/unflag
```

#### Bulk Operations
```
POST   /api/admin/v1/bookings/bulk/cancel
POST   /api/admin/v1/bookings/bulk/update-status
```

#### Special Views
```
GET    /api/admin/v1/bookings/flagged/all
GET    /api/admin/v1/bookings/activity-log
```

---

## Backward Compatibility

### ✅ **Existing Clients Continue to Work**

All existing API routes continue to work without any changes:

```
/api/login                    → Works (v1)
/api/bookings                 → Works (v1)
/api/business/bookings/calendar → Works (v1)
/admin/bookings/dashboard     → Works (v1)
```

**No breaking changes!** Existing clients don't need to update their code.

---

## Migration Guide for Clients

### Option 1: Continue Using Legacy Routes (No Changes)

```javascript
// This continues to work
axios.post('/api/login', credentials)
axios.get('/api/business/bookings/calendar?month=1&year=2026')
```

### Option 2: Migrate to Versioned Routes (Recommended)

```javascript
// Update to use explicit versioning
axios.post('/api/v1/login', credentials)
axios.get('/api/business/v1/bookings/calendar?month=1&year=2026')

// Benefits:
// - Explicit version dependency
// - Clear API contract
// - Easier to plan for future updates
```

---

## Future Versioning Strategy

### When to Release v2

Release a new major version when you need to make **breaking changes**:

1. **Remove deprecated endpoints**
2. **Change response structure**
3. **Modify required parameters**
4. **Change authentication method**

### Example v2 Implementation

```php
// routes/v2/api.php
Route::prefix('v2')->group(function () {
    require base_path('routes/v2/api.php');
});
```

**New endpoints:**
```
/api/v2/login    → New version
/api/v1/login    → Old version (maintained for backward compatibility)
/api/login       → Points to v2 (latest)
```

### Version Sunset Policy

When releasing v2:

1. **Announce v1 deprecation** (12 months notice)
2. **Maintain v1** for at least 12 months
3. **Add deprecation headers** to v1 responses:
   ```http
   X-API-Deprecated: true
   X-API-Sunset-Date: 2027-01-11
   X-API-Alternative: /api/v2
   ```

4. **Monitor v1 usage** and notify active users
5. **Decommission v1** after sunset date

---

## File Structure

```
routes/
├── api.php              # Main API router with version info
├── api.php.backup       # Original routes backup
├── v1/                  # Version 1 routes
│   ├── api.php          # Main API v1
│   ├── business.php     # Business API v1
│   └── admin.php        # Admin API v1
├── business.php         # Legacy business routes (maintained)
└── admin.php            # Legacy admin routes (maintained)

app/Http/Controllers/API/
└── V1/
    └── VersionController.php  # API version information
```

---

## Technical Implementation

### Route Loading Order

1. **Versioned routes** are loaded first (`/api/v1/*`)
2. **Legacy routes** are loaded second (`/api/*`)
3. This ensures both patterns work correctly

### Middleware Application

```php
// Main API
Route::prefix('v1')->group(function () {
    require base_path('routes/v1/api.php');
});

// Business API (versioned)
Route::middleware(['api','jwt.verify','business'])
    ->prefix('api/business/v1')
    ->group(base_path('routes/v1/business.php'));

// Business API (legacy - maintains compatibility)
Route::middleware(['api','jwt.verify','business'])
    ->prefix('api/business')
    ->group(base_path('routes/v1/business.php'));
```

---

## Testing API Versioning

### Check Version Info
```bash
curl http://bookrah.test/api
curl http://bookrah.test/api/version
```

### Test Versioned Endpoints
```bash
# v1 endpoints
curl http://bookrah.test/api/v1/categories
curl http://bookrah.test/api/business/v1/bookings/calendar?month=1&year=2026
curl http://bookrah.test/api/admin/v1/bookings/dashboard

# Legacy endpoints (should still work)
curl http://bookrah.test/api/categories
curl http://bookrah.test/api/business/bookings/calendar?month=1&year=2026
```

### View All Routes
```bash
# View v1 routes
php artisan route:list --path=api/v1

# View business v1 routes
php artisan route:list --path=business/v1

# View admin v1 routes
php artisan route:list --path=admin/v1

# View all API routes
php artisan route:list --path=api
```

---

## Benefits of API Versioning

### ✅ **For Developers**
- Clear API contracts
- Easier to maintain multiple versions
- Safer deployments
- Better testing and documentation

### ✅ **For Clients**
- Explicit version dependency
- Advance notice of changes
- Time to migrate
- No forced upgrades

### ✅ **For Business**
- Gradual feature rollout
- A/B testing different versions
- Backward compatibility
- Client communication

---

## Best Practices

### DO ✅
- Use semantic versioning (MAJOR.MINOR.PATCH)
- Document all changes between versions
- Provide migration guides
- Give 6-12 months deprecation notice
- Monitor usage of old versions
- Add deprecation headers

### DON'T ❌
- Don't break backward compatibility without major version bump
- Don't skip versions (v1 → v3)
- Don't deprecate without warning
- Don't remove old versions immediately
- Don't make breaking changes in minor versions

---

## Rollback Plan

If you need to rollback API versioning:

```bash
# 1. Restore original api.php
cp routes/api.php.backup routes/api.php

# 2. Remove v1 route files
rm -rf routes/v1/

# 3. Restore bootstrap/app.php
git checkout bootstrap/app.php

# 4. Clear route cache
php artisan route:clear
php artisan config:clear
```

---

## Summary

✅ **API versioning successfully implemented**
- Version 1 endpoints: `/api/v1/*`, `/api/business/v1/*`, `/api/admin/v1/*`
- Full backward compatibility maintained
- Legacy routes continue to work
- Version information endpoint available
- Ready for future v2 when needed

**No breaking changes for existing clients!**

---

## Support

For questions or issues with API versioning, contact the development team or check:
- API documentation: `/api` or `/api/version`
- Route list: `php artisan route:list --path=api`
- This document: `API_VERSIONING.md`