How kougianos/rest-api-aggregator works
Main Components
• Client/Consumer: The entry point of requests to the aggregator service.
– Application Entry Point (Application.java) that wires up the Spring Boot application.
– Configuration Layer: Components like AppProperties and WebClientConfig configure the application behavior and the reactive WebClient (with timeouts, etc.).
– Request Router & Handler: Classes like ServiceRouter and ServiceHandler route and process incoming requests and determine what APIs to call.
– Throttling & Batching Mechanism: The queue-related classes (CustomQueue, QueueManager, and QueueScheduler) are the heart of the throttling and batching functionality.
– External API Client: The ExternalApiClient calls out to the external backend service (which hosts the Pricing, Track, and Shipments APIs) asynchronously using Spring WebFlux (reactive programming).
– Aggregation Service: AggregationService is responsible for merging responses and generating the final aggregated response.
– Utility and DTO Components: Supporting classes such as GenericMap and Constants that help with data conversion and maintaining contract consistency.
• External Backend Service: This represents the external system that the aggregator calls (with endpoints for pricing, track, and shipments).
Relationships and Data Flow
– Incoming HTTP requests are handled by the request router (ServiceRouter/ServiceHandler).
– The request’s parameters determine which of the External API calls need to be made.
– For each API type (pricing, track, shipments), requests are added to corresponding queues (implemented via CustomQueue).
– A Scheduler (QueueScheduler) runs periodically to check these queues. It “fills” any incomplete queues (using a dummy value mechanism) and releases waiting threads if the queue isn’t full, ensuring that responses are returned within the SLA.
– Once the throttling/batching criteria are met, the ExternalApiClient is triggered to make the outbound asynchronous calls via a reactive WebClient.
– The AggregationService collects and merges the responses into a GenericMap before sending the aggregated response back to the client.
• The ExternalApiClient call is configured with a read timeout (5 seconds), and there is an asynchronous reactive chain (using Mono/Flux) that ties the flow together.
Key Architectural Patterns and Design Principles
• Microservice and API Gateway style: Even though this is a single service, its role is to combine multiple external APIs into one façade.
• Reactive Programming: The entire flow employs Spring WebFlux, meaning that requests are handled asynchronously and in a non-blocking fashion.
• Throttling and Batching: Managed by a combination of LinkedBlockingQueue (extended by CustomQueue) and a scheduler. The design pattern here is somewhat of a “buffering” pattern to intercept and batch requests.
• Separation of Concerns: Different packages handle configuration, routing, service logic, and utility functions giving a cleaner separation between the API handling, aggregation logic, and background processing.