diff --git a/src/docs/asciidoc/index.adoc b/src/docs/asciidoc/index.adoc index 0c7857c7a9a..afae295261b 100644 --- a/src/docs/asciidoc/index.adoc +++ b/src/docs/asciidoc/index.adoc @@ -14,11 +14,12 @@ JDBC, R2DBC, O/R Mapping, XML Marshalling. STOMP Messaging. <> :: Spring WebFlux, WebClient, WebSocket, RSocket. -<> :: JMS, JCA, JMX, Email, Tasks, Scheduling, Caching. +<> :: REST Clients, JMS, JCA, JMX, +Email, Tasks, Scheduling, Caching. <> :: Kotlin, Groovy, Dynamic Languages. <> :: Spring properties. -https://github.com/spring-projects/spring-framework/wiki[*Wiki*] :: What's New, Upgrade Notes, Supported Versions, -and other cross-version information. +https://github.com/spring-projects/spring-framework/wiki[*Wiki*] :: What's New, +Upgrade Notes, Supported Versions, and other cross-version information. ifdef::backend-html5[] NOTE: This documentation is also available as {docs-spring-framework}/reference/pdf/index.pdf[PDF]. diff --git a/src/docs/asciidoc/integration.adoc b/src/docs/asciidoc/integration.adoc index f9023e9f39d..039c4921445 100644 --- a/src/docs/asciidoc/integration.adoc +++ b/src/docs/asciidoc/integration.adoc @@ -12,19 +12,34 @@ a number of technologies. [[rest-client-access]] -== REST Endpoints +== REST Clients -The Spring Framework provides two choices for making calls to REST endpoints: +The Spring Framework provides the following choices for making calls to REST endpoints: + +* <> - non-blocking, reactive client w fluent API. +* <> - synchronous client with template method API. +* <> - annotated interface with generated, dynamic proxy implementation. + + +[[rest-webclient]] +=== `WebClient` + +`WebClient` is a non-blocking, reactive client to perform HTTP requests. It was +introduced in 5.0 and offers an alternative to the `RestTemplate`, with support for +synchronous, asynchronous, and streaming scenarios. + +`WebClient` supports the following: + +* Non-blocking I/O. +* Reactive Streams back pressure. +* High concurrency with fewer hardware resources. +* Functional-style, fluent API that takes advantage of Java 8 lambdas. +* Synchronous and asynchronous interactions. +* Streaming up to or streaming down from a server. + +See <> for more details. -* <>: The original Spring REST client with a synchronous, template -method API. -* <>: a non-blocking, reactive alternative -that supports both synchronous and asynchronous as well as streaming scenarios. -NOTE: As of 5.0 the `RestTemplate` is in maintenance mode, with only minor requests for -changes and bugs to be accepted going forward. Please, consider using the -<> which offers a more modern API and -supports sync, async, and streaming scenarios. [[rest-resttemplate]] @@ -34,6 +49,10 @@ The `RestTemplate` provides a higher level API over HTTP client libraries. It ma easy to invoke REST endpoints in a single line. It exposes the following groups of overloaded methods: +NOTE: `RestTemplate` is in maintenance mode, with only requests for minor +changes and bugs to be accepted. Please, consider using the +<> instead. + [[rest-overview-of-resttemplate-methods-tbl]] .RestTemplate methods [cols="1,3"] @@ -344,6 +363,151 @@ to `multipart/form-data` by the `FormHttpMessageConverter`. If the `MultiValueMa If necessary the `Content-Type` may also be set explicitly. +[[rest-http-interface]] +=== HTTP Interface + +The Spring Frameworks lets you define an HTTP service as a Java interface with annotated +methods for HTTP exchanges. You can then generate a proxy that implements this interface +and performs the exchanges. This helps to simplify HTTP remote access which often +involves a facade that wraps the details of using the underlying HTTP client. + +To start, declare an interface with annotated, HTTP exchange methods: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + interface RepositoryService { + + @GetExchange("/repos/{owner}/{repo}") + Repository getRepository(@PathVariable String owner, @PathVariable String repo); + + // more HTTP exchange methods... + + } +---- + +Now you create a proxy for the interface that performs the declared exchanges through +the `WebClient`: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + WebClient client = WebClient.builder() + .baseUrl("https://api.github.com/") + .build(); + + HttpServiceProxyFactory proxyFactory = + HttpServiceProxyFactory.builder(new WebClientAdapter(client)).build(); + + RepositoryService service = proxyFactory.createClient(RepositoryService.class); +---- + +An HTTP service interface can declare common attributes at the type level: + +[source,java,indent=0,subs="verbatim,quotes"] +---- + @HttpExchange(url = "/repos/{owner}/{repo}", accept = "application/vnd.github.v3+json") + interface RepositoryService { + + @GetExchange + Repository getRepository(@PathVariable String owner, @PathVariable String repo); + + @PatchExchange(contentType = MediaType.APPLICATION_FORM_URLENCODED_VALUE) + void updateRepository(@PathVariable String owner, @PathVariable String repo, + @RequestParam String name, @RequestParam String description, @RequestParam String homepage); + + } +---- + + +[[rest-http-interface-method-parameters]] +==== Method Parameters + +Annotated, HTTP exchange methods support flexible method signatures with the following +method parameters: + +[cols="1,2", options="header"] +|=== +| Controller method argument | Description + +| `URI` +| Dynamically set the URL for the request, overriding the annotation's `url` attribute. + +| `HttpMethod` +| Dynamically set the HTTP method for the request, overriding the annotation's `method` attribute + +| `@RequestHeader` +| Add a request header or mutliple headers. The argument may be a `Map` or + `MultiValueMap` with multiple headers, a `Collection` of values, or an + individual value. Type conversion is supported for non-String values. + +| `@PathVariable` +| Add a variable for expand a placeholder in the request URL. The argument may be a + `Map` with multiple variables, or an individual value. Type conversion + is supported for non-String values. + +| `@RequestBody` +| Provide the body of the request either as an Object to be serialized, or a + Reactive Streams `Publisher` such as `Mono`, `Flux`, or any other async type supported + through the configured `ReactiveAdapterRegistry`. + +| `@RequestParam` +| Add a request parameter or mutliple parameters. The argument may be a `Map` + or `MultiValueMap` with multiple parameters, a `Collection` of values, or + an individual value. Type conversion is supported for non-String values. + + When `"content-type"` is set to `"application/x-www-form-urlencoded"`, request + parameters are encoded in the request body. Otherwise, they are added as URL query + parameters. + +| `@CookieValue` +| Add a cookie or mutliple cookies. The argument may be a `Map` or + `MultiValueMap` with multiple cookies, a `Collection` of values, or an + individual value. Type conversion is supported for non-String values. + +|=== + + +[[rest-http-interface-return-values]] +==== Return Values + +Annotated, HTTP exchange methods support the following return values: + +[cols="1,2", options="header"] +|=== +| Controller method return value | Description + +| `void`, `Mono` +| Perform the given request, and release the response content, if any. + +| `HttpHeaders`, `Mono` +| Perform the given request, release the response content, if any, and return the + response headers. + +| ``, `Mono` +| Perform the given request and decode the response content to the declared return type. + +| ``, `Flux` +| Perform the given request and decode the response content to a stream of the declared + element type. + +| `ResponseEntity`, `Mono>` +| Perform the given request, and release the response content, if any, and return a + `ResponseEntity` with the status and headers. + +| `ResponseEntity`, `Mono>` +| Perform the given request, decode the response content to the declared return type, and + return a `ResponseEntity` with the status, headers, and the decoded body. + +| `Mono>` +| Perform the given request, decode the response content to a stream of the declared + element type, and return a `ResponseEntity` with the status, headers, and the decoded + response body stream. + +|=== + +TIP: You can also use any other async or reactive types registered in the +`ReactiveAdapterRegistry`. + + [[jms]] diff --git a/src/docs/asciidoc/web-reactive.adoc b/src/docs/asciidoc/web-reactive.adoc index 7e170bbd181..c199e90e08e 100644 --- a/src/docs/asciidoc/web-reactive.adoc +++ b/src/docs/asciidoc/web-reactive.adoc @@ -17,6 +17,18 @@ include::web/webflux.adoc[leveloffset=+1] include::web/webflux-webclient.adoc[leveloffset=+1] + +[[webflux-http-interface-client]] +== HTTP Interface Client + +The Spring Frameworks lets you define an HTTP service as a Java interface with HTTP +exchange methods. You can then generate a proxy that implements this interface and +performs the exchanges. This helps to simplify HTTP remote access and provides additional +flexibility for to choose an API style such as synchronous or reactive. + +See <> for details. + + include::web/webflux-websocket.adoc[leveloffset=+1] diff --git a/src/docs/asciidoc/web/webmvc-client.adoc b/src/docs/asciidoc/web/webmvc-client.adoc index 147344c78d6..0936a06ce0b 100644 --- a/src/docs/asciidoc/web/webmvc-client.adoc +++ b/src/docs/asciidoc/web/webmvc-client.adoc @@ -13,8 +13,8 @@ This section describes options for client-side access to REST endpoints. Spring REST client and exposes a simple, template-method API over underlying HTTP client libraries. -NOTE: As of 5.0 the `RestTemplate` is in maintenance mode, with only minor requests for -changes and bugs to be accepted going forward. Please, consider using the +NOTE: As of 5.0 the `RestTemplate` is in maintenance mode, with only requests for minor +changes and bugs to be accepted. Please, consider using the <> which offers a more modern API and supports sync, async, and streaming scenarios. @@ -40,3 +40,16 @@ In contrast to `RestTemplate`, `WebClient` supports the following: * Streaming up to or streaming down from a server. See <> for more details. + + + + +[[webmvc-http-interface]] +== HTTP Interface + +The Spring Frameworks lets you define an HTTP service as a Java interface with HTTP +exchange methods. You can then generate a proxy that implements this interface and +performs the exchanges. This helps to simplify HTTP remote access and provides additional +flexibility for to choose an API style such as synchronous or reactive. + +See <> for details.