Skip to content

Commit 7c1b168

Browse files
philwebbphilwebb
committed
Overhaul reference documentation for RestClient
Reorder "Calling REST services" documentation and add a new section covering `RestClient`. See gh-36213
1 parent 5e01c66 commit 7c1b168

File tree

6 files changed

+222
-67
lines changed

6 files changed

+222
-67
lines changed

‎spring-boot-project/spring-boot-docs/src/docs/asciidoc/anchor-rewrite.properties

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1020,3 +1020,6 @@ howto.testing.testcontainers.dynamic-properties=features.testing.testcontainers.
10201020

10211021
# gh-32905
10221022
container-images.efficient-images.unpacking=deployment.efficient.unpacking
1023+
1024+
# Spring Boot 3.1 - 3.2 migrations
1025+
io.rest-client.resttemplate.http-client=io.rest-client.clienthttprequestfactory

‎spring-boot-project/spring-boot-docs/src/docs/asciidoc/io/rest-client.adoc

Lines changed: 106 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -1,80 +1,23 @@
11
[[io.rest-client]]
22
== Calling REST Services
3-
If your application calls remote REST services, Spring Boot makes that very convenient using a `RestTemplate` or a `WebClient`.
4-
5-
[[io.rest-client.resttemplate]]
6-
=== RestTemplate
7-
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.
8-
Since `RestTemplate` instances often need to be customized before being used, Spring Boot does not provide any single auto-configured `RestTemplate` bean.
9-
It does, however, auto-configure a `RestTemplateBuilder`, which can be used to create `RestTemplate` instances when needed.
10-
The auto-configured `RestTemplateBuilder` ensures that sensible `HttpMessageConverters` are applied to `RestTemplate` instances.
11-
12-
The following code shows a typical example:
13-
14-
include::code:MyService[]
15-
16-
`RestTemplateBuilder` includes a number of useful methods that can be used to quickly configure a `RestTemplate`.
17-
For example, to add BASIC authentication support, you can use `builder.basicAuthentication("user", "password").build()`.
18-
19-
20-
21-
[[io.rest-client.resttemplate.http-client]]
22-
==== RestTemplate HTTP Client
23-
Spring Boot will auto-detect which HTTP client to use with `RestTemplate` depending on the libraries available on the application classpath.
24-
In order of preference, the following clients are supported:
25-
26-
. Apache HttpClient
27-
. OkHttp
28-
. Jetty HttpClient
29-
. Simple JDK client (`HttpURLConnection`)
30-
31-
If multiple clients are available on the classpath, the most preferred client will be used.
32-
33-
34-
35-
[[io.rest-client.resttemplate.customization]]
36-
==== RestTemplate Customization
37-
There are three main approaches to `RestTemplate` customization, depending on how broadly you want the customizations to apply.
38-
39-
To make the scope of any customizations as narrow as possible, inject the auto-configured `RestTemplateBuilder` and then call its methods as required.
40-
Each method call returns a new `RestTemplateBuilder` instance, so the customizations only affect this use of the builder.
41-
42-
To make an application-wide, additive customization, use a `RestTemplateCustomizer` bean.
43-
All such beans are automatically registered with the auto-configured `RestTemplateBuilder` and are applied to any templates that are built with it.
44-
45-
The following example shows a customizer that configures the use of a proxy for all hosts except `192.168.0.5`:
46-
47-
include::code:MyRestTemplateCustomizer[]
48-
49-
Finally, you can define your own `RestTemplateBuilder` bean.
50-
Doing so will replace the auto-configured builder.
51-
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`.
52-
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:
53-
54-
include::code:MyRestTemplateBuilderConfiguration[]
55-
56-
The most extreme (and rarely used) option is to create your own `RestTemplateBuilder` bean without using a configurer.
57-
In addition to replacing the auto-configured builder, this also prevents any `RestTemplateCustomizer` beans from being used.
58-
59-
60-
61-
[[io.rest-client.resttemplate.ssl]]
62-
==== RestTemplate SSL Support
63-
If you need custom SSL configuration on the `RestTemplate`, you can apply an <<features#features.ssl.bundles,SSL bundle>> to the `RestTemplateBuilder` as shown in this example:
64-
65-
include::code:MyService[]
3+
Spring Boot provides various convenient ways to call remote REST services.
4+
If you are developing a non-blocking reactive application and you're using Spring WebFlux, then you can use `WebClient`.
5+
If you prefer blocking APIs then you can use `RestClient` or `RestTemplate`.
666

677

688

699
[[io.rest-client.webclient]]
7010
=== WebClient
71-
If you have Spring WebFlux on your classpath, you can also choose to use `WebClient` to call remote REST services.
72-
Compared to `RestTemplate`, this client has a more functional feel and is fully reactive.
11+
If you have Spring WebFlux on your classpath we recommend that you use `WebClient` to call remote REST services.
12+
The `WebClient` interface provides a functional style API and is fully reactive.
7313
You can learn more about the `WebClient` in the dedicated {spring-framework-docs}/web-reactive.html#webflux-client[section in the Spring Framework docs].
7414

75-
Spring Boot creates and pre-configures a `WebClient.Builder` for you.
15+
TIP: If you are not writing a reactive Spring WebFlux application you can use the a <<io#io.rest-client.restclient,`RestClient`>> instead of a `WebClient`.
16+
This provides a similar functional API, but is blocking rather than reactive.
17+
18+
Spring Boot creates and pre-configures a prototype `WebClient.Builder` bean for you.
7619
It is strongly advised to inject it in your components and use it to create `WebClient` instances.
77-
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.
20+
Spring Boot is configuring that builder to share HTTP resources and reflect codecs setup in the same fashion as the server ones (see <<web#web.reactive.webflux.httpcodecs,WebFlux HTTP codecs auto-configuration>>), and more.
7821

7922
The following code shows a typical example:
8023

@@ -131,3 +74,99 @@ The following code shows a typical example:
13174

13275
include::code:MyService[]
13376

77+
78+
79+
[[io.rest-client.restclient]]
80+
=== RestClient
81+
If you are not using Spring WebFlux or Project Reactor in your application we recommend that you use `RestClient` to call remote REST services.
82+
83+
The `RestClient` interface provides a functional style blocking API.
84+
85+
Spring Boot creates and pre-configures a prototype `RestClient.Builder` bean for you.
86+
It is strongly advised to inject it in your components and use it to create `RestClient` instances.
87+
Spring Boot is configuring that builder with `HttpMessageConverters` and an appropriate `ClientHttpRequestFactory`.
88+
89+
The following code shows a typical example:
90+
91+
include::code:MyService[]
92+
93+
94+
95+
[[io.rest-client.restclient.customization]]
96+
==== RestClient Customization
97+
There are three main approaches to `RestClient` customization, depending on how broadly you want the customizations to apply.
98+
99+
To make the scope of any customizations as narrow as possible, inject the auto-configured `RestClient.Builder` and then call its methods as required.
100+
`RestClient.Builder` instances are stateful: Any change on the builder is reflected in all clients subsequently created with it.
101+
If you want to create several clients with the same builder, you can also consider cloning the builder with `RestClient.Builder other = builder.clone();`.
102+
103+
To make an application-wide, additive customization to all `RestClient.Builder` instances, you can declare `RestClientCustomizer` beans and change the `RestClient.Builder` locally at the point of injection.
104+
105+
Finally, you can fall back to the original API and use `RestClient.create()`.
106+
In that case, no auto-configuration or `RestClientCustomizer` is applied.
107+
108+
109+
110+
[[io.rest-client.resttemplate]]
111+
=== RestTemplate
112+
Spring Framework's {spring-framework-api}/web/client/RestTemplate.html[`RestTemplate`] class predates `RestClient` and is the classic way that many applications use to call remote REST services.
113+
You might choose to use `RestTemplate` when you have existing code that you don't want to migrate to `RestClient`, or because you're already familiar with the `RestTemplate` API.
114+
115+
Since `RestTemplate` instances often need to be customized before being used, Spring Boot does not provide any single auto-configured `RestTemplate` bean.
116+
It does, however, auto-configure a `RestTemplateBuilder`, which can be used to create `RestTemplate` instances when needed.
117+
The auto-configured `RestTemplateBuilder` ensures that sensible `HttpMessageConverters` and an appropriate `ClientHttpRequestFactory` are applied to `RestTemplate` instances.
118+
119+
The following code shows a typical example:
120+
121+
include::code:MyService[]
122+
123+
`RestTemplateBuilder` includes a number of useful methods that can be used to quickly configure a `RestTemplate`.
124+
For example, to add BASIC authentication support, you can use `builder.basicAuthentication("user", "password").build()`.
125+
126+
127+
128+
[[io.rest-client.resttemplate.customization]]
129+
==== RestTemplate Customization
130+
There are three main approaches to `RestTemplate` customization, depending on how broadly you want the customizations to apply.
131+
132+
To make the scope of any customizations as narrow as possible, inject the auto-configured `RestTemplateBuilder` and then call its methods as required.
133+
Each method call returns a new `RestTemplateBuilder` instance, so the customizations only affect this use of the builder.
134+
135+
To make an application-wide, additive customization, use a `RestTemplateCustomizer` bean.
136+
All such beans are automatically registered with the auto-configured `RestTemplateBuilder` and are applied to any templates that are built with it.
137+
138+
The following example shows a customizer that configures the use of a proxy for all hosts except `192.168.0.5`:
139+
140+
include::code:MyRestTemplateCustomizer[]
141+
142+
Finally, you can define your own `RestTemplateBuilder` bean.
143+
Doing so will replace the auto-configured builder.
144+
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`.
145+
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:
146+
147+
include::code:MyRestTemplateBuilderConfiguration[]
148+
149+
The most extreme (and rarely used) option is to create your own `RestTemplateBuilder` bean without using a configurer.
150+
In addition to replacing the auto-configured builder, this also prevents any `RestTemplateCustomizer` beans from being used.
151+
152+
153+
154+
[[io.rest-client.resttemplate.ssl]]
155+
==== RestTemplate SSL Support
156+
If you need custom SSL configuration on the `RestTemplate`, you can apply an <<features#features.ssl.bundles,SSL bundle>> to the `RestTemplateBuilder` as shown in this example:
157+
158+
include::code:MyService[]
159+
160+
161+
162+
[[io.rest-client.clienthttprequestfactory]]
163+
=== HTTP Client Detection for RestClient and RestTemplate
164+
Spring Boot will auto-detect which HTTP client to use with `RestClient` and `RestTemplate` depending on the libraries available on the application classpath.
165+
In order of preference, the following clients are supported:
166+
167+
. Apache HttpClient
168+
. OkHttp
169+
. Jetty HttpClient
170+
. Simple JDK client (`HttpURLConnection`)
171+
172+
If multiple clients are available on the classpath, the most preferred client will be used.

‎spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/io/restclient/restclient/Details.java

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
/*
2+
* Copyright 2012-2023 the original author or authors.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* https://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package org.springframework.boot.docs.io.restclient.restclient;
18+
19+
public class Details {
20+
21+
}

‎spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/io/restclient/restclient/MyService.java

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
/*
2+
* Copyright 2012-2023 the original author or authors.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* https://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package org.springframework.boot.docs.io.restclient.restclient;
18+
19+
import org.springframework.stereotype.Service;
20+
import org.springframework.web.client.RestClient;
21+
22+
@Service
23+
public class MyService {
24+
25+
private final RestClient restClient;
26+
27+
public MyService(RestClient.Builder restClientBuilder) {
28+
this.restClient = restClientBuilder.baseUrl("https://example.org").build();
29+
}
30+
31+
public Details someRestCall(String name) {
32+
return this.restClient.get().uri("/{name}/details", name).retrieve().body(Details.class);
33+
}
34+
35+
}

‎spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/io/restclient/restclient/Details.kt

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
/*
2+
* Copyright 2012-2023 the original author or authors.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* https://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package org.springframework.boot.docs.io.restclient.restclient
18+
19+
class Details

‎spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/io/restclient/restclient/MyService.kt

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
/*
2+
* Copyright 2012-2022 the original author or authors.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* https://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package org.springframework.boot.docs.io.restclient.restclient
18+
19+
import org.springframework.boot.docs.io.restclient.restclient.ssl.Details
20+
import org.springframework.stereotype.Service
21+
import org.springframework.web.client.RestClient
22+
23+
@Service
24+
class MyService(restClientBuilder: RestClient.Builder) {
25+
26+
private val restClient: RestClient
27+
28+
init {
29+
restClient = restClientBuilder.baseUrl("https://example.org").build()
30+
}
31+
32+
fun someRestCall(name: String?): Details {
33+
return restClient.get().uri("/{name}/details", name)
34+
.retrieve().body(Details::class.java)!!
35+
}
36+
37+
}
38+

0 commit comments

Comments
 (0)