Clarify difference between Target<T> and RequestInterceptor in docs regarding header injection

[anno1985]

I've had a look at the docs to figure out how to inject a header for my requests, and they mention Target<T> and RequestInterceptor. The respective section opens:

In cases where headers should differ for the same api based on different endpoints or where per-request customization is required, headers can be set as part of the client using a RequestInterceptor or a Target.

The docs also state:

When you need to change all requests, regardless of their target, you'll want to configure a RequestInterceptor

So, if I want to set header A to foo for target 1, and to bar for target 2, I use Target<T>, otherwise (if I want to set the same value for the same header for all requests and targets) RequestInterceptor.

What I find confusing is that the target(...) method is the terminator for the Feign Builder. So I can't specify two different targets on the same builder (unless I assign a builder to variable before calling target(...), but I don't think I have seen that done anywhere in the docs), and the RequestInterceptor is set on the Builder, too - which leads me to ask, where is the difference, really?

Isn't the request interceptor in pretty much all cases going to be per target as well?

[kdavisk6]

A Target represents a facade around the provided client interface, locked to a uri endpoint, therefore, it is not possible to create more than one Target from a single builder, with different target uri endpoints. You will need to create a new builder that results in a new Target for each interface and uri endpoint you need.

Request Interceptors can be used to add headers and do not have to be unique instances per target, so long as each target that uses the interceptor is ok with the same behavior and the interceptor implementation is thread safe. It's ok to share Request Interceptor instances across Targets, that's what the documentation is trying to tell you. I agree it's confusing. A simpler explanation would be to say:

To customize headers for each request method on a Target, a RequestInterceptor can be used. RequestInterceptors can be shared across Target instances and are expected to be thread-safe. RequestInterceptors are applied to all request methods on a Target.

If you need per method customization, a custom Target is required, as the a RequestInterceptor does not have access to the current method metadata.