Robust API Client Framework

The API Client Framework is Java library for building fault tolerant and robust client libraries with automatic retries. The name robusto is derived from a particularly strong and resilient family of coffee beans, paying homage to both the Java language in which it is written, and to it's primary goal of helping to build robust API clients across a variety of applications. It is based on the Netflix Hystrix and Spring Retry projects. The API Client Framework allows you to use any client library you want, is highly configurable, and comes with a number of add-ons for health checks, response caching, and more.

Purpose

The robusto framework is intended for use with any HTTP client library, or even other protocols. Basically any remote command that may fail and is a good candidate for retrying can be executed within the confines of the framework. At HomeAdvisor we use this primarily for HTTP based API calls, but other protocols using any library could easily be used.

How It Works

There are 2 key steps when executing a remote command in the API Client Framework:

1. Remote Service Lookup/Discovery - Finding a remote service/host using any mechanism you want such as Eureka or Curator.
2. Remote Service Call - Executing a remote call, such as HTTP, using a service/host 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.

Background

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.