112 lines
6.4 KiB
Plaintext
112 lines
6.4 KiB
Plaintext
[[io.rest-client]]
|
|
== Calling REST Services
|
|
If your application calls remote REST services, Spring Boot makes that very convenient using a `RestTemplate` or a `WebClient`.
|
|
|
|
[[io.rest-client.resttemplate]]
|
|
=== RestTemplate
|
|
If you need to call remote REST services from your application, you can use the Spring Framework's {spring-framework-api}/web/client/RestTemplate.html[`RestTemplate`] class.
|
|
Since `RestTemplate` instances often need to be customized before being used, Spring Boot does not provide any single auto-configured `RestTemplate` bean.
|
|
It does, however, auto-configure a `RestTemplateBuilder`, which can be used to create `RestTemplate` instances when needed.
|
|
The auto-configured `RestTemplateBuilder` ensures that sensible `HttpMessageConverters` are applied to `RestTemplate` instances.
|
|
|
|
The following code shows a typical example:
|
|
|
|
include::code:MyService[]
|
|
|
|
TIP: `RestTemplateBuilder` includes a number of useful methods that can be used to quickly configure a `RestTemplate`.
|
|
For example, to add BASIC auth support, you can use `builder.basicAuthentication("user", "password").build()`.
|
|
|
|
|
|
|
|
[[io.rest-client.resttemplate.http-client]]
|
|
==== RestTemplate HTTP Client
|
|
Spring Boot will auto-detect which HTTP client to use with `RestTemplate` depending on the libraries available on the application classpath.
|
|
In order of preference, the following clients are supported:
|
|
|
|
. Apache HttpClient
|
|
. OkHttp
|
|
. Simple JDK client (`HttpURLConnection`)
|
|
|
|
If multiple clients are available on the classpath, the most preferred client will be used.
|
|
|
|
|
|
|
|
[[io.rest-client.resttemplate.customization]]
|
|
==== RestTemplate Customization
|
|
There are three main approaches to `RestTemplate` customization, depending on how broadly you want the customizations to apply.
|
|
|
|
To make the scope of any customizations as narrow as possible, inject the auto-configured `RestTemplateBuilder` and then call its methods as required.
|
|
Each method call returns a new `RestTemplateBuilder` instance, so the customizations only affect this use of the builder.
|
|
|
|
To make an application-wide, additive customization, use a `RestTemplateCustomizer` bean.
|
|
All such beans are automatically registered with the auto-configured `RestTemplateBuilder` and are applied to any templates that are built with it.
|
|
|
|
The following example shows a customizer that configures the use of a proxy for all hosts except `192.168.0.5`:
|
|
|
|
include::code:MyRestTemplateCustomizer[]
|
|
|
|
Finally, you can define your own `RestTemplateBuilder` bean.
|
|
Doing so will replace the auto-configured builder.
|
|
If you want any `RestTemplateCustomizer` beans to be applied to your custom builder, as the auto-configuration would have done, configure it using a `RestTemplateBuilderConfigurer`.
|
|
The following example exposes a `RestTemplateBuilder` that matches what Spring Boot's auto-configuration would have done, except that custom connect and read timeouts are also specified:
|
|
|
|
include::code:MyRestTemplateBuilderConfiguration[]
|
|
|
|
The most extreme (and rarely used) option is to create your own `RestTemplateBuilder` bean without using a configurer.
|
|
In addition to replacing the auto-configured builder, this also prevents any `RestTemplateCustomizer` beans from being used.
|
|
|
|
|
|
|
|
[[io.rest-client.webclient]]
|
|
=== WebClient
|
|
If you have Spring WebFlux on your classpath, you can also choose to use `WebClient` to call remote REST services.
|
|
Compared to `RestTemplate`, this client has a more functional feel and is fully reactive.
|
|
You can learn more about the `WebClient` in the dedicated {spring-framework-docs}/web/webflux-webclient.html[section in the Spring Framework docs].
|
|
|
|
Spring Boot creates and pre-configures a `WebClient.Builder` for you.
|
|
It is strongly advised to inject it in your components and use it to create `WebClient` instances.
|
|
Spring Boot is configuring that builder to share HTTP resources, reflect codecs setup in the same fashion as the server ones (see <<web#web.reactive.webflux.httpcodecs,WebFlux HTTP codecs auto-configuration>>), and more.
|
|
|
|
The following code shows a typical example:
|
|
|
|
include::code:MyService[]
|
|
|
|
|
|
|
|
[[io.rest-client.webclient.runtime]]
|
|
==== WebClient Runtime
|
|
Spring Boot will auto-detect which `ClientHttpConnector` to use to drive `WebClient` depending on the libraries available on the application classpath.
|
|
In order of preference, the following clients are supported:
|
|
|
|
. Reactor Netty
|
|
. Jetty RS client
|
|
. Apache HttpClient
|
|
. JDK HttpClient
|
|
|
|
If multiple clients are available on the classpath, the most preferred client will be used.
|
|
|
|
The `spring-boot-starter-webflux` starter depends on `io.projectreactor.netty:reactor-netty` by default, which brings both server and client implementations.
|
|
If you choose to use Jetty as a reactive server instead, you should add a dependency on the Jetty Reactive HTTP client library, `org.eclipse.jetty:jetty-reactive-httpclient`.
|
|
Using the same technology for server and client has its advantages, as it will automatically share HTTP resources between client and server.
|
|
|
|
Developers can override the resource configuration for Jetty and Reactor Netty by providing a custom `ReactorResourceFactory` or `JettyResourceFactory` bean - this will be applied to both clients and servers.
|
|
|
|
If you wish to override that choice for the client, you can define your own `ClientHttpConnector` bean and have full control over the client configuration.
|
|
|
|
You can learn more about the {spring-framework-docs}/web/webflux-webclient/client-builder.html[`WebClient` configuration options in the Spring Framework reference documentation].
|
|
|
|
|
|
|
|
[[io.rest-client.webclient.customization]]
|
|
==== WebClient Customization
|
|
There are three main approaches to `WebClient` customization, depending on how broadly you want the customizations to apply.
|
|
|
|
To make the scope of any customizations as narrow as possible, inject the auto-configured `WebClient.Builder` and then call its methods as required.
|
|
`WebClient.Builder` instances are stateful: Any change on the builder is reflected in all clients subsequently created with it.
|
|
If you want to create several clients with the same builder, you can also consider cloning the builder with `WebClient.Builder other = builder.clone();`.
|
|
|
|
To make an application-wide, additive customization to all `WebClient.Builder` instances, you can declare `WebClientCustomizer` beans and change the `WebClient.Builder` locally at the point of injection.
|
|
|
|
Finally, you can fall back to the original API and use `WebClient.create()`.
|
|
In that case, no auto-configuration or `WebClientCustomizer` is applied.
|