Platform API

The MyNATCA Platform provides Express.js-based REST API endpoints for authentication, member management, sync operations, and Discord verification services. The platform serves as the central integration hub for the entire MyNATCA ecosystem.

Interactive API Documentation

🎯 View Interactive Swagger Documentation → (opens in a new tab)

The Platform API includes interactive OpenAPI 3.0 documentation with "Try it out" functionality. Access the Swagger UI to explore all endpoints, view request/response schemas, and test API calls directly from your browser.

Features:

Complete endpoint documentation with examples
Interactive request testing
Authentication support (API Key & Session)
Auto-generated from code (always up-to-date)

Note: The Swagger documentation link above uses the development URL. When the platform is deployed to production, update this link to https://platform.natca.org/api-docs

Base URLs

Production:  https://platform.natca.org
Development: http://localhost:1300

API Base:
Production:  https://platform.natca.org/api
Development: http://localhost:1300/api

API Docs:
Production:  https://platform.natca.org/api-docs
Development: http://localhost:1300/api-docs

Authentication

The platform uses two authentication methods:

1. Session-Based Authentication (Primary)

Session cookies for web applications and user-facing APIs:

// Frontend authentication check
const response = await fetch('/api/auth/session', {
  credentials: 'include' // Include session cookies
});
 
if (response.ok) {
  const { authenticated, user } = await response.json();
  // User is authenticated
}

2. Service Authentication (Internal)

Service keys for internal application communication:

# Service-to-service authentication
curl -X POST /api/auth/service \
  -H "Content-Type: application/json" \
  -d '{"serviceKey": "discord_service_key", "serviceName": "discord"}'

API Endpoint Coverage

The Platform API provides 22 documented endpoints across 6 categories:

Category	Endpoints	Authentication
Health	1 endpoint	None required
Authentication	5 endpoints	Session / Service Key
Members	5 endpoints	API Key / Session
Verification	2 endpoints	Mixed
Sync	5 endpoints	Sync API Key
Rackspace Email	3 endpoints	Session

📖 For complete endpoint documentation with request/response schemas, visit the Interactive Swagger Documentation (opens in a new tab)

Note: Additional endpoints exist beyond those documented in Swagger. See the "Advanced Endpoints" section below for legacy and administrative endpoints that may not be included in the interactive documentation.

Quick Reference

Health Check

`GET /api/health`

Check platform service health status. No authentication required.

View in Swagger → (opens in a new tab)

Authentication Endpoints

All authentication endpoints are documented with full request/response examples in Swagger:

GET /api/auth/login - Initiate Auth0 OAuth flow
GET /api/auth/callback - Handle Auth0 callback
GET /api/auth/session - Get current session info
GET /api/auth/logout - End session
POST /api/auth/service - Service-to-service auth

View in Swagger → (opens in a new tab)

Member Management

Member endpoints require API Key authentication (X-API-Key header):

GET /api/member/{memberNumber} - Get member by member number
GET /api/member/discord/{discordId} - Get member by Discord ID
POST /api/member/{memberNumber}/link-discord - Link Discord account
POST /api/member/{memberNumber}/unlink-discord - Unlink Discord account
POST /api/member/unlink - Unlink (session-authenticated)

View in Swagger → (opens in a new tab)

Discord Verification

Verification flow endpoints for Discord member verification:

POST /api/verify/start - Start verification session
GET /api/verify/complete/{verificationId} - Complete verification

View in Swagger → (opens in a new tab)

Rackspace Email Management

Endpoints for managing @natca.net email addresses for eligible members:

POST /api/rackspace/check-availability - Check email format availability for a member
POST /api/rackspace/create-email - Create new natca.net email account
POST /api/rackspace/reset-password - Reset existing natca.net email password

View in Swagger → (opens in a new tab)

Detailed Documentation:

Data Synchronization

`POST /api/sync/trigger`

Triggers MySQL to Supabase data synchronization.

View in Swagger → (opens in a new tab)

Request Body:

{
  "apiKey": "sync_api_key",
  "syncType": "members"
}

Valid sync types:

members: Sync member data
facilities: Sync facility data
regions: Sync region data
positions: Sync position data
all: Full synchronization (all data types)

Response (200 OK):

{
  "success": true,
  "message": "Member sync triggered",
  "syncType": "members"
}

Additional Platform Endpoints

The following endpoints are implemented in the Platform API but are not yet included in the Swagger documentation. These endpoints provide additional functionality for synchronization monitoring, data access, and administrative operations.

Sync Operations API

Get Sync Status

Monitor the current synchronization status and health.

GET /api/sync/status
Authorization: Bearer <service_token>

Response (200 OK):

{
  "success": true,
  "status": {
    "last_sync": {
      "timestamp": "2023-01-01T12:00:00.000Z",
      "status": "completed",
      "duration_ms": 59500,
      "records_processed": 5912,
      "records_succeeded": 5905,
      "records_failed": 7
    },
    "current_sync": null,
    "next_scheduled_sync": "2023-01-01T18:00:00.000Z",
    "health_status": "healthy"
  }
}

Get Sync Health

Detailed health information about synchronization processes.

GET /api/sync/health
Authorization: Bearer <service_token>

Response (200 OK):

{
  "success": true,
  "health": {
    "status": "healthy",
    "last_sync_age_hours": 2.5,
    "success_rate": 0.998,
    "average_duration_ms": 58000,
    "database_connections": {
      "mysql": "connected",
      "supabase": "connected"
    },
    "issues": []
  }
}

Member Data Endpoints

Search Members

Search for members across the platform with filters.

GET /api/members/search?q=john&facility=ZTL&limit=20
Authorization: Bearer <service_token>

Response (200 OK):

{
  "success": true,
  "members": [
    {
      "member_number": "123456",
      "first_name": "John",
      "last_name": "Doe",
      "facility_code": "ZTL",
      "region_code": "ASO",
      "member_type_id": 6,
      "discord_verified": true
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Get All Facilities

Retrieve facility information for platform integrations.

GET /api/facilities
Authorization: Bearer <service_token>

Response (200 OK):

{
  "success": true,
  "facilities": [
    {
      "facility_code": "ZTL",
      "facility_name": "Atlanta TRACON",
      "region_code": "ASO",
      "active": true,
      "member_count": 250
    }
  ]
}

Get All Regions

Retrieve regional data for organizational structure.

GET /api/regions
Authorization: Bearer <service_token>

Response (200 OK):

{
  "success": true,
  "regions": [
    {
      "region_code": "ASO",
      "region_name": "Air Safety Organization",
      "facility_count": 15,
      "member_count": 1250
    }
  ]
}

System Status Endpoints

Detailed Status

Comprehensive platform status information.

GET /api/status
Authorization: Bearer <service_token>

Response (200 OK):

{
  "success": true,
  "application": {
    "name": "MyNATCA Platform API",
    "version": "1.0.0",
    "environment": "production",
    "uptime": 86400,
    "memory_usage": {
      "used": 45.2,
      "total": 128.0,
      "percentage": 35.3
    }
  },
  "database": {
    "supabase": {
      "status": "connected",
      "response_time_ms": 15
    },
    "mysql": {
      "status": "connected",
      "response_time_ms": 25
    }
  },
  "sync_service": {
    "status": "healthy",
    "last_sync": "2023-01-01T12:00:00.000Z",
    "success_rate": 0.998
  }
}

Administrative Endpoints

Platform Statistics

Get comprehensive platform usage and health statistics.

GET /api/admin/stats
Authorization: Bearer <admin_jwt_token>

Response (200 OK):

{
  "success": true,
  "stats": {
    "total_members": 5000,
    "active_facilities": 150,
    "sync_performance": {
      "average_duration_ms": 58000,
      "success_rate": 0.998,
      "last_24h_syncs": 24
    },
    "api_usage": {
      "requests_today": 15000,
      "average_response_time_ms": 120
    }
  }
}

Sync Management

Administrative control over synchronization processes.

POST /api/admin/sync/trigger
Authorization: Bearer <admin_jwt_token>
Content-Type: application/json
 
{
  "type": "full",
  "priority": "high",
  "notify_completion": true
}

Proxy Middleware

The platform includes dynamic proxy middleware that forwards requests to external APIs with automatic Bearer token injection:

// Example: Request to MyNATCA API through platform proxy
fetch('/api/mynatca/Member/12345', {
  credentials: 'include' // Platform automatically adds Bearer token
});

Proxy Configuration:

Target URL mapping via database configuration
Automatic Bearer token forwarding from user sessions
CORS header management
Path rewriting support

Environment Variables

Required Configuration

# Server Configuration
PORT=1300
NODE_ENV=production
 
# Database
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
 
# Authentication
AUTH0_DOMAIN=mynatca.auth0.com
AUTH0_CLIENT_ID=your_client_id
AUTH0_CLIENT_SECRET=your_client_secret
AUTH0_REDIRECT_URI=https://platform.natca.org/api/auth/callback
AUTH0_BASE_URL=https://platform.natca.org
 
# Session Management
SESSION_SECRET=your_secure_session_secret
REDIS_URL=redis://localhost:6379
 
# Service Keys
SYNC_API_KEY=sync_service_key
DISCORD_SERVICE_KEY=discord_service_key
 
# External Services
DISCORD_BOT_URL=https://discord.natca.org

Error Handling

All API endpoints use consistent error response format:

{
  "error": "Error description",
  "message": "Detailed error message",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Common HTTP status codes:

200 OK: Success
400 Bad Request: Invalid request parameters
401 Unauthorized: Authentication required
403 Forbidden: Insufficient permissions
404 Not Found: Resource not found
500 Internal Server Error: Server error

Rate Limiting

Current Limits

Service requests: 10000 requests/hour per service
Admin requests: 5000 requests/hour per admin
Health checks: No rate limit

Response Headers

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9847
X-RateLimit-Reset: 1640995200
X-RateLimit-Window: 3600

Error Handling

Standard Error Format

{
  "success": false,
  "error": "SYNC_FAILED",
  "message": "Data synchronization failed due to database connection timeout",
  "details": {
    "sync_id": "sync_2023010112345",
    "failed_operations": ["members"],
    "retry_after": 300
  },
  "timestamp": "2023-01-01T12:00:00.000Z",
  "request_id": "req_550e8400-e29b-41d4"
}

Common Error Codes

Sync Errors

SYNC_IN_PROGRESS - Another sync operation is currently running
SYNC_FAILED - Synchronization operation failed
DATABASE_CONNECTION_ERROR - Unable to connect to source or target database
SYNC_TIMEOUT - Synchronization operation timed out

Data Errors

INVALID_FACILITY_CODE - Facility code not found in system
MEMBER_DATA_INCOMPLETE - Required member data fields missing
DUPLICATE_RECORD - Attempt to create duplicate record

Integration Examples

Monitoring Sync Health

// Monitor synchronization health
async function checkSyncHealth() {
  const response = await fetch('https://platform.natca.org/api/sync/health', {
    headers: {
      'Authorization': `Bearer ${serviceToken}`,
      'Content-Type': 'application/json'
    }
  });
 
  const health = await response.json();
 
  if (health.success && health.health.status === 'healthy') {
    console.log('Sync is healthy');
  } else {
    console.warn('Sync issues detected:', health.health.issues);
  }
}

Triggering Data Sync

// Trigger a full data synchronization
async function triggerSync() {
  const response = await fetch('https://platform.natca.org/api/sync/all', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${serviceToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      batch_size: 1000,
      dry_run: false,
      types: ['members', 'facilities', 'regions', 'positions']
    })
  });
 
  const result = await response.json();
  console.log('Sync completed:', result.sync_id);
}

Best Practices

Sync Operations

Monitor sync health regularly using the health endpoints
Use appropriate batch sizes for large data operations
Implement retry logic for failed synchronizations
Schedule syncs during low-traffic periods

Performance

Cache facility and region data to reduce API calls
Use pagination for large member searches
Implement circuit breakers for external service calls
Monitor rate limits and implement backoff strategies

Error Handling

Always check the success field in API responses
Implement proper logging for troubleshooting
Handle rate limiting gracefully with retry mechanisms
Monitor error rates and alert on anomalies

The Platform API is the backbone of the MyNATCA ecosystem, ensuring reliable data synchronization and providing essential integration capabilities for all platform components.

Authentication & Authorization MyNATCA API