Home
The API Client Framework is Java library for building fault tolerant and robust client libraries with automatic retries. It is based on the Netflix Hystrix and Spring Retry projects. The API Client Framework allows you to use any HTTP client library you want, is highly configurable, and comes with a number of add-ons for health checks, response caching, and more.
There are 2 key components to the API Client Framework:
- Remote Service Lookup/Discovery - Finding a remote service using any mechanism you want such as Eureka or Curator.
- Remote Service Call - Executing a remote call, such as HTTP, using a service from step 1.
Because service discovery typically involves a network call, both of the above steps are executed within the confines of a Hystrix Command and Spring Retry. A typical remote service call can be summed up as follows:
The remote service call can be any remote network call you want. At HomeAdvisor this is typically an HTTP call using Spring Web Client.
And note that you have the full flexibility of Hystrix command execution using synchronous, asynchronous, or reactive execution.
The motivation behind the API Client Framework was building HTTP clients in our microservice architecture. When we create a new microservice with HTTP endpoints, we typically also create a corresponding client library to make it easy to integrate that new service with the rest of our system. We needed a way for developers to quickly write new clients that were standardized and fault tolerant, while minimizing as much boilerplate as possible so they could focus on the core business logic of clients.
Hystrix is a great framework for executing commands that are prone to failure, and provides several great features such as command collapsing and caching to avoid duplicate calls, circuit breaker logic to allow networks to self heal during periods of failures, and metrics reporting to get insight into command volume, failures, etc. The one thing it does not include, however, is a retry policy. This is by design and fits many use cases perfectly fine, but for our needs at HomeAdvisor, we needed to be able to retry certain types of HTTP failures (specifically the 5xx series of responses, as well as the 408 request timeout), while not retrying others (forbidden, bad requests, etc).
To get around the lack of retry in Hystrix, we added Spring Retry into the framework to handle retry and backoff. Spring Retry is highly customizable and uses exception hierarchies to determine whether or not retries are needed, which makes using different HTTP clients within the framework pretty straightforward, since each library typically has its own exception hierarchy that model HTTP response codes. It also provides different backoff policies to determine how long to pause in between each retry.