Feat/api read endpoints

[RichardCMX]

🎯 Pull Request: API Read Endpoints (Stops, Routes, Trips, Arrivals/ETAs, Status, Alerts)

📋 Summary

Implements comprehensive API read endpoints for GTFS data access including stops, routes, trips, real-time arrival predictions, system health checks, and service alerts with global pagination support.

This PR resolves issue #27 (Read endpoints: stops, routes, trips, arrivals/ETAs, status, alerts)

✨ Features Added

🚀 New API Endpoints

• GET /api/arrivals/ - Real-time arrival predictions from external ETA service

  • Integrates with Project 4 ETA service via ETAS_API_URL
  • Returns trip/route info, real-time times, progression status, accessibility
  • Error handling: 502 on upstream failure, 501 if not configured
  • Parameter validation: stop_id (required), limit (1-100)

• GET /api/status/ - System health check endpoint

  • Reports PostgreSQL and Redis connection status
  • Useful for monitoring and load balancer health checks

• GET /api/alerts/ - Service alerts from GTFS Realtime

  • Paginated list of current service alerts
  • Includes alert headers, descriptions, and affected entities

• GET /api/feed-messages/ - GTFS Realtime feed messages

  • Paginated access to raw GTFS Realtime feed data
  • Includes timestamp and feed version information

• GET /api/stop-time-updates/ - Real-time stop time updates

  • Paginated list of schedule deviations and predictions
  • Includes arrival/departure delays and schedule relationships

• Core GTFS Read Endpoints (via DRF ViewSets)

  • Stops, routes, trips, and related GTFS Schedule entities
  • Full CRUD operations with filtering capabilities

📄 Pagination

• Global LimitOffsetPagination enabled (page size 50)
• Consistent pagination format across all endpoints
• Configurable via query parameters

⚙️ Configuration

• ETAS_API_URL environment variable for external ETA service integration
  • Points to Project 4 real-time prediction service
  • If not configured, /api/arrivals/ returns 501 Not Implemented

🧪 Testing

• Comprehensive test suite for arrivals endpoint (9 test cases)
  • Mocked upstream API responses using unittest.mock
  • Response structure validation
  • Error propagation (upstream failures → 502)
  • Parameter validation (stop_id required, limit bounds: 1-100)
  • Configuration validation (501 when ETAS_API_URL not set)
  • Wrapped payload handling ({"results": [...]})
  • Time format validation (HH:MM:SS)
• All tests include descriptive docstrings

📚 Documentation

• Updated CHANGELOG.md with all new endpoints
• Enhanced OpenAPI/Swagger documentation
  • Examples for all new endpoints
  • Pagination documentation
  • Filter fields properly mapped to model fields
• Updated api/tests/README.md with:
  • Arrivals testing documentation
  • Mocked HTTP request testing approach
  • 9 documented test cases
• README updates with new endpoint documentation and usage examples
• Includes merged documentation from feat/storage-reading-dal

📝 Commits

• Merge from feat/storage-reading-dal (includes DAL and Fuseki removal)
• docs: update CHANGELOG for API read endpoints feature
• docs(tests): add docstrings to arrivals endpoint test suite
• docs(tests): update test README with arrivals endpoint documentation

🔍 Related Issues

Closes #27

✅ Checklist

• Code follows project style guidelines
• Tests added and passing (9 test cases for arrivals)
• Documentation updated (CHANGELOG, test README, OpenAPI)
• No breaking changes introduced
• OpenAPI schema updated with examples
• Mocked external service calls in tests
• Global pagination enabled

📸 Example Usage

# Get real-time arrivals with ETAs
curl "http://localhost:8000/api/arrivals/?stop_id=STOP_123&limit=5"

# Check system health
curl "http://localhost:8000/api/status/"

# Get service alerts (paginated)
curl "http://localhost:8000/api/alerts/?limit=10&offset=0"

# Get GTFS Realtime feed messages
curl "http://localhost:8000/api/feed-messages/"

# Get stop time updates
curl "http://localhost:8000/api/stop-time-updates/"

🎯 Next Steps

After merging, the following branches will need to be rebased/merged to include these changes:

• feature/search-health-endpoints
• feature/auth-rate-limits
• feature/client-management
• And subsequent feature branches