Search and Health Endpoints with Multilingual Support

[RichardCMX]

📋 Summary

Implements intelligent search functionality with fuzzy matching and accent-insensitive search for multilingual support, plus comprehensive health monitoring endpoints. Adds interactive Swagger UI for API testing and exploration.

This PR resolves issue #28 (Search/autocomplete endpoints and health checks)

✨ Features Added

🔍 Search API with Advanced Matching

• GET /api/search/ - Unified search endpoint with intelligent ranking

  • Query parameters:

    • q (required): Search query string
    • type (optional): 'stops', 'routes', or 'all' (default)
    • limit (optional): Maximum results (1-100), defaults to 20
    • feed_id (optional): Limit search to specific feed

  • Key Features:

    • 🎯 Relevance Scoring (0.0-1.0): Exact matches = 1.0, sorted by relevance
    • 🔍 Fuzzy Text Matching: PostgreSQL pg_trgm extension handles typos
    • 🌐 Multilingual Support: Unaccent extension for accent-insensitive search
      • "San José" matches "San Jose" and vice versa
      • Perfect for Spanish, Portuguese, and other accented languages
    • 📊 Multi-field Search: Searches names, descriptions across stops and routes
    • ⚡ Optimized Queries: Trigram similarity with intelligent fallback

🏥 Health & Monitoring Endpoints

• GET /api/health/ - Simple health check

  • Returns {"status": "ok", "timestamp": "..."}
  • Lightweight, no database queries
  • Perfect for basic uptime monitoring and load balancer health checks

• GET /api/ready/ - Comprehensive readiness check

  • Returns 200 when ready, 503 when not ready
  • Validates:
    • Database connectivity (PostgreSQL)
    • Current GTFS feed availability
  • Returns detailed status including feed_id, database health, and timestamp
  • Ideal for Kubernetes readiness probes and deployment validation

🗄️ PostgreSQL Extensions

• pg_trgm extension - Trigram similarity for fuzzy text matching
• unaccent extension - Accent-insensitive text matching for multilingual support
• Configured via:
  • docker/db/init.sql - Automatic setup on database creation
  • datahub/test_runner.py - Custom test runner ensures extensions in test database
  • Works in both development and test environments

🎮 Interactive API Documentation

• Swagger UI - Added at /api/docs/swagger/

  • Interactive forms for all API endpoints
  • "Try it out" functionality for live testing
  • Real-time request/response preview
  • Parameter descriptions and validation
  • Perfect for exploring and testing the search API

• ReDoc - Available at /api/docs/

  • Clean, organized API documentation
  • Detailed endpoint descriptions
  • Request/response examples

🧪 Testing

Search Endpoint Tests (test_search.py)

• Exact name matching validation
• Partial name matching tests
• Description-based search tests
• Type filtering (stops, routes, all)
• Limit parameter validation (bounds checking)
• Relevance score validation
• Query parameter requirement tests
• Comprehensive edge case coverage

Health Endpoint Tests (test_health.py)

• Health endpoint structure validation
• Ready endpoint with/without current feed
• Database connectivity error handling
• Feed availability checks
• Multiple current feeds handling
• Response structure validation
• Status value validation (ready/not_ready)
• Error condition testing

📚 Documentation

• CHANGELOG.md - Comprehensive documentation of all features
• README.md - Updated with:
  • Multilingual search documentation
  • Accent-insensitive search examples
  • Interactive API documentation section
  • Health and readiness endpoint usage
  • Swagger UI and ReDoc information
• Test Documentation - All tests include descriptive docstrings

📝 Commits

• Merge from feat/api-read-endpoints (includes DAL and previous features)
• feat: add unaccent support for multilingual search
• fix(db): add missing pg_trgm extension setup (cherry-picked from future branch)
• feat: add Swagger UI for interactive API documentation
• docs: add CHANGELOG for search and health endpoints feature
• docs: update README with unaccent and Swagger UI documentation

🔍 Related Issues

Closes #28

✅ Checklist

• Code follows project style guidelines
• Tests added and passing (search and health endpoints)
• Documentation updated (README, CHANGELOG)
• No breaking changes introduced
• OpenAPI schema updated with drf-spectacular
• PostgreSQL extensions configured
• Interactive Swagger UI added

📸 Example Usage

Search with Multilingual Support

# Search with accented characters
curl "http://localhost:8000/api/search/?q=San+José&type=stops"

# Search without accents (still finds "San José")
curl "http://localhost:8000/api/search/?q=San+Jose&type=stops"

# Fuzzy search (handles typos)
curl "http://localhost:8000/api/search/?q=Univercidad&type=routes"

# Search everything
curl "http://localhost:8000/api/search/?q=UCR&limit=10"

Health Checks

# Simple health check
curl "http://localhost:8000/api/health/"

# Readiness check
curl "http://localhost:8000/api/ready/"

Interactive Testing

Visit in your browser:

• Swagger UI: http://localhost:8000/api/docs/swagger/
• ReDoc: http://localhost:8000/api/docs/

🎯 Next Steps

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

• feature/auth-rate-limits
• feature/client-management
• feature/security-performance
• feature/admin-panel-metrics
• feature/unit-integration-contract-tests

💡 Technical Notes

• Search Performance: Trigram indexing provides sub-second search on thousands of stops/routes
• Multilingual: Unaccent extension normalizes Unicode characters for matching
• Graceful Degradation: Search falls back to basic text matching if extensions unavailable
• Health Checks: /health/ is lightweight (no DB), /ready/ is comprehensive (validates DB and feeds)
• Test Isolation: Custom test runner ensures PostgreSQL extensions available in test database