Phase 2 - API Interface

5.1 RESTful API Design

WIA-UNI-008 APIs follow RESTful principles with standard HTTP methods:

• GET: Retrieve routes, bookings, tracking data
• POST: Create new bookings, cargo shipments, vehicles
• PUT: Update existing resources
• DELETE: Cancel bookings, deregister vehicles

5.2 Authentication and Security

OAuth 2.0 token-based authentication with scopes for granular access control:

• routes:read / routes:write
• bookings:read / bookings:write
• tracking:read
• cargo:read / cargo:write

5.3 Key API Endpoints

Routes API

• GET /v1/routes - List routes with filtering
• GET /v1/routes/{id} - Get route details
• POST /v1/routes - Create new route

Bookings API

• GET /v1/bookings/availability - Search availability
• POST /v1/bookings - Create booking
• GET /v1/bookings/{id} - Get booking details
• DELETE /v1/bookings/{id} - Cancel booking

Tracking API

• GET /v1/tracking/vehicles/{id} - Real-time vehicle tracking
• GET /v1/tracking/bookings/{id} - Track passenger journey
• WebSocket /v1/tracking/stream - Subscribe to live updates

5.4 Webhooks

Event-driven notifications for booking confirmations, cancellations, delays, and cargo status changes. Webhooks use HMAC-SHA256 signatures for security.

5.5 Rate Limiting

Fair usage policies: 1,000 req/hour (standard), 10,000 req/hour (premium), custom for enterprise.