​

API Architecture

​

API Architecture Diagram

​

API Structure Overview

​

Framework: Hono

• Lightweight: Minimal overhead with fast startup times
• TypeScript-first: Full type safety across the application
• Edge-optimized: Designed for serverless and edge deployments
• Middleware ecosystem: Rich middleware support for common patterns

​

Request Processing Pipeline

1. AWS API Gateway: Routes incoming requests to Lambda function
2. Hono Application: Processes requests through middleware chain
3. Authentication: Bearer token validation for protected routes
4. Route Handling: Dispatch to appropriate handler based on path
5. Response Formatting: Structured JSON responses with error handling

​

Middleware Stack

​

Core Middleware (Applied to all routes)

• Request/response logging for debugging and monitoring
• Structured log format for CloudWatch integration

• Automatic gzip compression for response bodies
• Reduces bandwidth usage and improves response times

• Formats JSON responses for better readability
• Development-friendly output formatting

• Global error handling with structured error responses
• HTTPException handling with proper status codes
• Fallback handling for unexpected errors

​

Authentication Middleware

• Validates Authorization: Bearer <token> headers
• Uses SG_CARS_TRENDS_API_TOKEN environment variable
• Applied to /v1/* and /trpc/* routes
• Workflow endpoints also require authentication

• Upstash Redis-based rate limiting implementation
• Configurable via FEATURE_FLAG_RATE_LIMIT
• Currently commented out but ready for activation

​

API Endpoints

​

Public Endpoints (No Authentication)

​

Documentation Endpoints

• Scalar API reference interface
• Interactive API exploration
• Generated from OpenAPI specification

• Machine-readable API specification
• OpenAPI 3.1.0 format
• Includes version info from package.json

• Service health monitoring endpoint
• Returns basic service status
• Used by load balancers and monitoring systems

​

Authenticated Endpoints (Bearer Token Required)

​

Data API v1 (/v1/*)

• Query Parameters:
  • month: Filter by specific month (YYYY-MM)
  • make: Filter by vehicle manufacturer
  • fuel_type: Filter by fuel type
  • Additional filtering options
• Response: Paginated vehicle registration data
• Caching: Redis-cached with TTL

• Query Parameters:
  • month: Filter by bidding month
  • vehicle_class: Filter by COE category
  • bidding_no: Filter by bidding exercise (1 or 2)
• Response: COE bidding results and premium data
• Includes PQP rates where applicable

• Returns list of months with available data
• Used for frontend date picker population
• Separate endpoints for cars and COE data availability

​

tRPC Integration (/trpc/*)

• Full TypeScript integration with automatic type inference
• Procedure-based architecture with input validation
• Context creation with authentication state
• Automatic serialization/deserialization

• Bearer token validation for all tRPC procedures
• Context includes authentication state
• Type-safe error handling

​

Workflow Endpoints (/workflows/*)

​

Workflow Management

• Triggers both cars and COE data processing workflows
• Authenticated endpoint for administrative use
• Returns workflow execution status

• QStash-triggered endpoint for cars data processing
• Handles file download, processing, and database updates
• Includes blog generation and social media posting

• QStash-triggered endpoint for COE data processing
• Processes bidding results and PQP data
• Conditional blog generation based on bidding cycle completion

​

Social Media Webhooks

• Handles LinkedIn posting workflow
• OAuth token management and refresh
• Business-focused content formatting

• Twitter API v2 integration
• Character limit handling and URL shortening
• Engagement-optimized content formatting

• Webhook-based Discord notifications
• Error reporting and status updates
• Community engagement features

• Bot-based channel messaging
• Markdown formatting support
• Channel-specific content delivery

​

Error Handling

​

Structured Error Responses

{
  "status": 200,
  "timestamp": "2024-01-01T12:00:00.000Z",
  "data": {...},
  "error": null
}

{
  "status": 400,
  "timestamp": "2024-01-01T12:00:00.000Z",
  "data": null,
  "error": {
    "message": "Detailed error description"
  }
}

​

HTTP Status Codes

• 200: Successful requests
• 400: Bad request (invalid parameters)
• 401: Unauthorized (missing or invalid token)
• 404: Resource not found
• 429: Rate limit exceeded (when enabled)
• 500: Internal server error

​

Global Error Handler

• HTTPException Handling: Preserves original status codes
• Unexpected Error Handling: Returns 500 with generic message
• Error Logging: Comprehensive error logging to CloudWatch
• Discord Notifications: Critical errors trigger Discord alerts

​

Performance Optimizations

​

Caching Strategy

• API responses cached with appropriate TTL
• Cache keys based on request parameters
• Cache invalidation on data updates
• Session and workflow state storage

• Cache-Control headers for static content
• ETags for conditional requests
• CDN integration for global distribution

​

Database Optimization

• Drizzle ORM with connection pooling
• Optimized for serverless Lambda execution
• Connection reuse across requests

• Strategic database indexes for common queries
• Batch operations for bulk data processing
• Prepared statements for performance

​

Lambda Function Configuration

• Architecture: ARM64 for cost efficiency
• Runtime: Node.js 22.x for latest performance features
• Timeout: 120 seconds for long-running workflows
• Memory: Optimized allocation based on usage patterns

​

Security Considerations

​

Authentication & Authorization

• Secure token-based authentication
• Environment variable-based token management
• No user session management required

• Tokens stored as environment variables
• Rotation capability without code changes
• Separate tokens for different environments

​

Data Protection

• Comprehensive input validation using Zod schemas
• SQL injection prevention through ORM
• Parameter sanitization and type checking

• Ready-to-enable rate limiting using Upstash Redis
• IP-based limiting with sliding window algorithm
• Configurable limits per environment

​

Monitoring & Observability

​

Logging

• JSON-formatted logs for machine readability
• CloudWatch Logs integration
• Request/response logging with correlation IDs

• Comprehensive error logging with stack traces
• Discord integration for critical error notifications
• Performance metrics and slow query detection

​

Health Monitoring

• Basic service availability monitoring
• Database connection verification
• Redis connectivity checks

• Automatic metrics collection
• Lambda function performance monitoring
• Custom metrics for business logic

​

Related Documentation

• System Architecture Overview
• Data Processing Workflows
• Database Schema
• API Service Documentation