Interceptors

A RequestInterceptor changes every request before it is sent. Use it for what all calls need and no method should repeat: an authentication header, a tracing id, a common query parameter. Every RequestInterceptor bean applies to every client, in @Order.

Why

A token or a request id added by hand to every method is noise, and one forgotten method sends an unauthenticated request. An interceptor adds it once, for all clients or for some, and runs again at every attempt, so a refreshed token reaches a retry.

Example

@Configuration()
class FeignSetup {
  // The user's token; the function may be async, and it is asked again at every attempt.
  @Bean()
  RequestInterceptor auth(TokenStore tokens) =>
      BearerTokenRequestInterceptor(() => tokens.accessToken);

  @Bean()
  @Order(10)
  RequestInterceptor requestIds() => RequestIds();
}

// Every call carries a request id; the catalog also gets the language.
final class RequestIds implements RequestInterceptor {
  @override
  void apply(RequestTemplate template) {
    template.header('X-Request-Id', newId());
    if (template.clientName == 'catalog') template.query('lang', 'en');
  }
}

RequestTemplate

Member Meaning
method, url The HTTP method and the full URL (base URL, path and query); an interceptor may replace them.
headers The request headers, to read or change.
body The encoded body, or null. Replacing it does not change the Content-Type.
header(name, value) Adds a value, as Feign's does. To replace a header, call removeHeader(name) first.
removeHeader(name) Removes a header.
query(name, value) Adds a query parameter.
methodKey Which method makes the call, such as CatalogClient#find(String); error decoders get the same key.
clientName The client's @FeignClient name, to act on some clients only.

How interceptors run

Ready-made interceptors

Interceptor Sends
BearerTokenRequestInterceptor(token) Authorization: Bearer ... from a function that may be async; adds nothing when it returns null.
BasicAuthRequestInterceptor(user, password) HTTP Basic credentials, encoded in ISO-8859-1 as Feign does; pass encoding: utf8 for other characters.

Which interceptors a client gets

  1. The application's RequestInterceptor beans and those of the client's @FeignClient(configuration:) classes, all together in @Order.
  2. Then the beans the request-interceptors property names, default's first, then the client's. A bean that is both runs once.

Beans of one client's configuration classes never reach the other clients (see Configuration).

Secrets

Send secrets as headers, not query parameters: the URL with its query is in the logs and in exception messages. Authorization, Proxy-Authorization, Cookie, Set-Cookie and DPoP are always masked in the logs; name others in sensitive-headers (see Logging).

In Spring (Java)

@Bean
RequestInterceptor requestIds() {
  return template -> template.header("X-Request-Id", newId());
}

The same interface. Each retry starts from a new template here; Feign runs the interceptors again on the same one, where header values pile up.

See also