vip-coordinator/frontend-old-20260125/dist/README-API.md

# VIP Coordinator API Documentation

## 📚 Overview

This document provides comprehensive API documentation for the VIP Coordinator system using **OpenAPI 3.0** (Swagger) specification. The API enables management of VIP transportation coordination, including flight tracking, driver management, and event scheduling.

## 🚀 Quick Start

### View API Documentation

1. **Interactive Documentation (Recommended):**
   ```bash
   # Open the interactive Swagger UI documentation
   open vip-coordinator/api-docs.html
   ```
   Or visit: `file:///path/to/vip-coordinator/api-docs.html`

2. **Raw OpenAPI Specification:**
   ```bash
   # View the YAML specification file
   cat vip-coordinator/api-documentation.yaml
   ```

### Test the API

The interactive documentation includes a "Try it out" feature that allows you to test endpoints directly:

1. Open `api-docs.html` in your browser
2. Click on any endpoint to expand it
3. Click "Try it out" button
4. Fill in parameters and request body
5. Click "Execute" to make the API call

## 📋 API Categories

### 🏥 Health
- `GET /api/health` - System health check

### 👥 VIPs
- `GET /api/vips` - Get all VIPs
- `POST /api/vips` - Create new VIP
- `PUT /api/vips/{id}` - Update VIP
- `DELETE /api/vips/{id}` - Delete VIP

### 🚗 Drivers
- `GET /api/drivers` - Get all drivers
- `POST /api/drivers` - Create new driver
- `PUT /api/drivers/{id}` - Update driver
- `DELETE /api/drivers/{id}` - Delete driver
- `GET /api/drivers/{driverId}/schedule` - Get driver's schedule
- `POST /api/drivers/availability` - Check driver availability
- `POST /api/drivers/{driverId}/conflicts` - Check driver conflicts

### ✈️ Flights
- `GET /api/flights/{flightNumber}` - Get flight information
- `POST /api/flights/{flightNumber}/track` - Start flight tracking
- `DELETE /api/flights/{flightNumber}/track` - Stop flight tracking
- `POST /api/flights/batch` - Get multiple flights info
- `GET /api/flights/tracking/status` - Get tracking status

### 📅 Schedule
- `GET /api/vips/{vipId}/schedule` - Get VIP's schedule
- `POST /api/vips/{vipId}/schedule` - Add event to schedule
- `PUT /api/vips/{vipId}/schedule/{eventId}` - Update event
- `DELETE /api/vips/{vipId}/schedule/{eventId}` - Delete event
- `PATCH /api/vips/{vipId}/schedule/{eventId}/status` - Update event status

### ⚙️ Admin
- `POST /api/admin/authenticate` - Admin authentication
- `GET /api/admin/settings` - Get admin settings
- `POST /api/admin/settings` - Update admin settings

## 💡 Example API Calls

### Create a VIP with Flight
```bash
curl -X POST http://localhost:3000/api/vips \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "organization": "Tech Corp",
    "transportMode": "flight",
    "flights": [
      {
        "flightNumber": "UA1234",
        "flightDate": "2025-06-26",
        "segment": 1
      }
    ],
    "needsAirportPickup": true,
    "needsVenueTransport": true,
    "notes": "CEO - requires executive transport"
  }'
```

### Add Event to VIP Schedule
```bash
curl -X POST http://localhost:3000/api/vips/{vipId}/schedule \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Meeting with CEO",
    "location": "Hyatt Regency Denver",
    "startTime": "2025-06-26T11:00:00",
    "endTime": "2025-06-26T12:30:00",
    "type": "meeting",
    "assignedDriverId": "1748780965562",
    "description": "Important strategic meeting"
  }'
```

### Check Driver Availability
```bash
curl -X POST http://localhost:3000/api/drivers/availability \
  -H "Content-Type: application/json" \
  -d '{
    "startTime": "2025-06-26T11:00:00",
    "endTime": "2025-06-26T12:30:00",
    "location": "Denver Convention Center"
  }'
```

### Get Flight Information
```bash
curl "http://localhost:3000/api/flights/UA1234?date=2025-06-26"
```

## 🔧 Tools for API Documentation

### 1. **Swagger UI (Recommended)**
- **What it is:** Interactive web-based API documentation
- **Features:** 
  - Try endpoints directly in browser
  - Auto-generated from OpenAPI spec
  - Beautiful, responsive interface
  - Request/response examples
- **Access:** Open `api-docs.html` in your browser

### 2. **OpenAPI Specification**
- **What it is:** Industry-standard API specification format
- **Features:**
  - Machine-readable API definition
  - Can generate client SDKs
  - Supports validation and testing
  - Compatible with many tools
- **File:** `api-documentation.yaml`

### 3. **Alternative Tools**

You can use the OpenAPI specification with other tools:

#### Postman
1. Import `api-documentation.yaml` into Postman
2. Automatically creates a collection with all endpoints
3. Includes examples and validation

#### Insomnia
1. Import the OpenAPI spec
2. Generate requests automatically
3. Built-in environment management

#### VS Code Extensions
- **OpenAPI (Swagger) Editor** - Edit and preview API specs
- **REST Client** - Test APIs directly in VS Code

## 📖 Documentation Best Practices

### Why OpenAPI/Swagger?

1. **Industry Standard:** Most widely adopted API documentation format
2. **Interactive:** Users can test APIs directly in the documentation
3. **Code Generation:** Can generate client libraries in multiple languages
4. **Validation:** Ensures API requests/responses match specification
5. **Tooling:** Extensive ecosystem of tools and integrations

### Documentation Features

- **Comprehensive:** All endpoints, parameters, and responses documented
- **Examples:** Real-world examples for all operations
- **Schemas:** Detailed data models with validation rules
- **Error Handling:** Clear error response documentation
- **Authentication:** Security requirements clearly specified

## 🔗 Integration Examples

### Frontend Integration
```javascript
// Example: Fetch VIPs in React
const fetchVips = async () => {
  const response = await fetch('/api/vips');
  const vips = await response.json();
  return vips;
};
```

### Backend Integration
```bash
# Example: Using curl to test endpoints
curl -X GET http://localhost:3000/api/health
curl -X GET http://localhost:3000/api/vips
curl -X GET http://localhost:3000/api/drivers
```

## 🚀 Next Steps

1. **Explore the Interactive Docs:** Open `api-docs.html` and try the endpoints
2. **Test with Real Data:** Use the populated test data to explore functionality
3. **Build Integrations:** Use the API specification to build client applications
4. **Extend the API:** Add new endpoints following the established patterns

## 📞 Support

For questions about the API:
- Review the interactive documentation
- Check the OpenAPI specification for detailed schemas
- Test endpoints using the "Try it out" feature
- Refer to the example requests and responses

The API documentation is designed to be self-service and comprehensive, providing everything needed to integrate with the VIP Coordinator system.