Summary of client-side REST options in MVC section

Author: rstoyanchev

src/docs/asciidoc/integration.adoc

@@ -948,14 +948,16 @@ plugging in third-party or custom solutions here.
 [[rest-client-access]]
 === Accessing REST endpoints
 
-The Spring Framework offers two choices for client-side access to REST endpoints:
+The Spring Framework has two choices for client-side access to REST endpoints:
 
 * <<rest-resttemplate>> -- the original Spring REST client with an API similar to other
-template classes in Spring, such as `JdbcTemplate`, `JmsTemplate` and others. The
-`RestTemplate` is built for synchronous use with the blocking I/O.
+template classes in Spring such as `JdbcTemplate`, `JmsTemplate` and others.
+`RestTemplate` has a synchronous API and relies on blocking I/O which is okay for
+client scenarios with low concurrency.
 * <<web-reactive.adoc#webflux-client,WebClient>> -- reactive client with a functional,
-fluent API from the `spring-webflux` module. It is built on a non-blocking foundation
-for async and sync scenarios and supports Reactive Streams back pressure.
+fluent API from the `spring-webflux` module. It relies on non-blocking I/O which allows it
+to support high concurrency more efficiently (i.e. using a small number of threads) than the
+`RestTemplate`. `WebClient` is a natural fit for streaming scenarios.
 
 
 [[rest-resttemplate]]
@@ -966,11 +968,6 @@ that correspond to each of the six main HTTP methods that make invoking many RES
 services a one-liner and enforce REST best practices.
 
 
-[NOTE]
-====
-RestTemplate has an asynchronous counter-part: see <<rest-async-resttemplate>>.
-====
-
 [[rest-overview-of-resttemplate-methods-tbl]]
 .Overview of RestTemplate methods
 [cols="1,3"]

src/docs/asciidoc/web.adoc

@@ -13,6 +13,8 @@ For reactive stack, web applications, go to <<web-reactive.adoc#spring-web-react
 
 include::web/webmvc.adoc[leveloffset=+1]
 
+include::web/webmvc-client.adoc[leveloffset=+1]
+
 include::web/webmvc-test.adoc[leveloffset=+1]
 
 include::web/websocket.adoc[leveloffset=+1]

src/docs/asciidoc/web/webmvc-client.adoc

@@ -0,0 +1,30 @@
+[[webmvc-client]]
+= REST Clients
+
+This section describes options for client-side access to REST endpoints.
+
+[[webmvc-resttemplate]]
+== RestTemplate
+
+`RestTemplate` is the original Spring REST client that follows a similar approach to other
+template classes in the Spring Framework (e.g. `JdbcTemplate`, `JmsTemplate`, etc.) by
+providing a list of parameterizable methods to perform HTTP requests.
+
+`RestTemplate` has a synchronous API and relies on blocking I/O. This is okay for
+client scenarios with low concurrency. In a server environment or when orchestrating a
+sequence of remote calls, prefer using the `WebClient` which provides a more efficient
+execution model including seamless support for streaming.
+
+See <<integration.adoc#rest-client-access,RestTemplate>> for more details on using the
+`RestTemplate`.
+
+
+[[webmvc-webclient]]
+== WebClient
+
+`WebClient` is a reactive client that provides an alternative to the `RestTemplate`. It
+exposes a functional, fluent API and relies on non-blocking I/O which allows it to support
+high concurrency more efficiently (i.e. using a small number of threads) than the
+`RestTemplate`. `WebClient` is a natural fit for streaming scenarios.
+
+See <<web-reactive.adoc#webflux-client,WebClient>> for more details on using the `WebClient`.