vip-coordinator/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):

   # 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:

   # 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

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

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

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

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

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

Backend Integration

# 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.