# API Versioning Documentation

## Overview

The Bookrah API implements proper versioning to ensure backward compatibility and allow for future enhancements without breaking existing clients.

## Version Structure

### URL Pattern

All API endpoints follow this pattern:
```
/api/v1/{resource}
```

### Version 1 Endpoints

#### Public Endpoints (No Authentication)
- `POST /api/v1/login` - User login
- `POST /api/v1/register` - User registration
- `POST /api/v1/google/login` - Google authentication
- `GET /api/v1/search` - Search companies
- `GET /api/v1/categories` - Get categories
- `GET /api/v1/company/{slug}` - Get company details

#### User Endpoints (JWT Required)
- `GET /api/v1/dashboard` - User dashboard
- `GET /api/v1/dashboard/bookings/recent` - Recent bookings
- `GET /api/v1/dashboard/summary` - User summary
- `GET /api/v1/dashboard/appointments-by-date` - Appointments by date
- `GET /api/v1/bookmarks` - Get user bookmarks
- `GET /api/v1/bookmarks/company/{company}` - Toggle bookmark
- `GET /api/v1/appointments` - Get user appointments

#### Business Endpoints (Business JWT Required)
- `GET /api/v1/business/dashboard` - Business dashboard
- `GET /api/v1/business/employees` - List employees
- `POST /api/v1/business/employees` - Create employee
- `GET /api/v1/business/employees/edit/{id}` - Get employee for edit
- `POST /api/v1/business/employees/update/{id}` - Update employee
- `DELETE /api/v1/business/employees/delete/{id}` - Delete employee
- `GET /api/v1/business/services` - List services
- `POST /api/v1/business/services` - Create service
- `GET /api/v1/business/bookings/calendar` - Get booking calendar
- `GET /api/v1/business/bookings/date` - Get bookings by date
- `GET /api/v1/business/clients` - List clients

#### Admin Endpoints (Admin JWT Required)
- `GET /api/v1/admin/bookings` - List all bookings
- `GET /api/v1/admin/bookings/dashboard` - Admin dashboard
- `GET /api/v1/admin/bookings/flagged/all` - Get flagged bookings
- `POST /api/v1/admin/bookings/bulk/cancel` - Bulk cancel bookings
- `POST /api/v1/admin/bookings/bulk/update-status` - Bulk update status
- `PUT /api/v1/admin/bookings/{id}` - Update booking
- `DELETE /api/v1/admin/bookings/{id}` - Delete booking

## Legacy Routes (Backward Compatibility)

For backward compatibility, some routes without the `/v1` prefix are still supported:

```
/api/business/*  → redirects to /api/v1/business/*
/api/admin/*     → redirects to /api/v1/admin/*
```

**Note:** These legacy routes are maintained for existing clients but may be deprecated in future versions. New integrations should use `/api/v1/*` endpoints.

## Controller Structure

```
app/Http/Controllers/API/
├── V1/
│   ├── Admin/
│   │   └── AdminBookingController.php
│   ├── Auth/
│   │   └── AuthenticationController.php
│   ├── Business/
│   │   ├── AddressController.php
│   │   ├── BioAndGalleryController.php
│   │   ├── BookingController.php
│   │   ├── ClientController.php
│   │   ├── CompanyController.php
│   │   ├── CompanyOpeningTimeController.php
│   │   ├── CompleteAccountController.php
│   │   ├── EmployeeController.php
│   │   ├── EmployeeShiftingController.php
│   │   └── ServiceController.php
│   ├── Frontend/
│   │   ├── Booking/
│   │   │   └── BookingController.php
│   │   ├── CompanyController.php
│   │   ├── ReviewController.php
│   │   ├── SearchController.php
│   │   └── SubscriptionController.php
│   ├── UserDashboard/
│   │   └── DashboardController.php
│   ├── AppointmentController.php
│   ├── BookmarkController.php
│   ├── HomeController.php
│   ├── UserController.php
│   └── VersionController.php
```

## Route Files Structure

```
routes/
├── api.php              → Main API entry point (with legacy support)
├── v1/
│   ├── api.php          → V1 API routes
│   ├── business.php     → V1 Business routes
│   └── admin.php        → V1 Admin routes
├── web.php              → Web routes
├── auth.php             → Authentication web routes
├── backend.php          → Admin panel web routes
└── console.php          → Console routes
```

## Namespace Convention

All V1 controllers use the namespace:
```php
namespace App\Http\Controllers\API\V1\{Category};
```

For example:
- Business controllers: `App\Http\Controllers\API\V1\Business`
- Admin controllers: `App\Http\Controllers\API\V1\Admin`
- Frontend controllers: `App\Http\Controllers\API\V1\Frontend`

## Versioning Strategy

### Adding New Versions

When introducing v2 of the API:

1. Create new controller directory: `app/Http/Controllers/API/V2/`
2. Copy and modify controllers from V1 with changes
3. Create route file: `routes/v2/api.php`
4. Add version group in `routes/api.php`:
   ```php
   Route::prefix('v2')->group(function () {
       require base_path('routes/v2/api.php');
   });
   ```

### Version Lifecycle

- **Current Stable**: v1 ( actively maintained)
- **Legacy**: Unversioned routes (deprecated, maintained for compatibility)
- **Future**: v2 (when needed)

### Deprecation Policy

When deprecating API versions:
1. Announce deprecation at least 6 months in advance
2. Add `X-API-Deprecated: true` header to deprecated endpoints
3. Add `X-API-Sunset: {date}` header with sunset date
4. Maintain deprecated endpoints for minimum 6 months after announcement

## Testing

### Test V1 Endpoints
```bash
# List all v1 routes
php artisan route:list --path=api/v1

# Test business endpoint
curl -X GET "http://bookrah.test/api/v1/business/employees" \
  -H "Authorization: Bearer {token}"

# Test admin endpoint
curl -X GET "http://bookrah.test/api/v1/admin/bookings" \
  -H "Authorization: Bearer {admin_token}"
```

## Migration Guide

### Migrating from Legacy to V1

**Old Endpoint:**
```
GET /api/business/employees
```

**New Endpoint:**
```
GET /api/v1/business/employees
```

**Changes:**
- Add `/v1` after `/api`
- Everything else remains the same
- Same authentication method
- Same request/response format

### Benefits of V1

1. **Clear Versioning**: Easy to identify API version
2. **Future-Proof**: Can add v2 without breaking v1
3. **Consistent Structure**: All APIs follow same pattern
4. **Better Organization**: Controllers organized by version
5. **Backward Compatible**: Legacy routes still work

## Best Practices

1. **Always use versioned endpoints** for new integrations
2. **Handle version-specific errors** gracefully
3. **Check API version** in request headers if needed
4. **Document version changes** in API documentation
5. **Maintain backward compatibility** within the same major version

## Header Information

### Request Headers
```
Authorization: Bearer {jwt_token}
Accept: application/json
Content-Type: application/json
X-API-Version: 1.0 (optional)
```

### Response Headers
```
X-API-Version: 1.0
X-Powered-By: Bookrah API
```

## Support

For questions or issues related to API versioning:
- Check this documentation first
- Review route list: `php artisan route:list --path=api/v1`
- Contact development team for version-specific issues