mp.restclient.adoc Maven / Gradle / Ivy
///////////////////////////////////////////////////////////////////////////////
Copyright (c) 2019, 2024 Oracle and/or its affiliates.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
///////////////////////////////////////////////////////////////////////////////
= Rest Client
:description: Helidon MP Rest Client
:feature-name: MicroProfile Rest Client
:microprofile-bundle: true
:keywords: helidon, rest, client, microprofile, micro-profile
:rootdir: {docdir}/..
include::{rootdir}/includes/mp.adoc[]
== Contents
- <>
- <>
- <>
- <>
- <>
- <>
== Overview
MicroProfile Rest Client adds the capability to invoke remote services by defining a Java interface with Jakarta REST
(JAX-RS) annotations that resembles a server-side resource class.
Helidon will automatically create a _proxy_ class for the interface and map local proxy calls to remote REST calls.
For more information, see link:{microprofile-rest-client-spec-url}[Rest Client For MicroProfile Specification].
include::{rootdir}/includes/dependencies.adoc[]
[source,xml]
----
io.helidon.microprofile.rest-client
helidon-microprofile-rest-client
----
== API
[cols="1,2"]
|===
|Class |Description
|org.eclipse.microprofile.rest.client.RestClientBuilder
|Base builder instance. Contains configuration options and a `build` method that creates the actual client instance.
|===
[cols="1,2"]
|===
|Annotation |Description
|@RegisterRestClient
|A marker annotation to register a client at runtime. This marker must be applied to any CDI managed clients.
|@RestClient
|RestClient qualifier which should be used on an CDI injection points.
|===
=== Creating a New Client Using a Builder [[creating-a-new-client]]
MicroProfile Rest Client can be created using a builder obtained from `RestClientBuilder.newBuilder()`.
The builder provides methods to specify the client interface to be proxied as well as to configure
additional details such as server URI, SSL context, connection timeouts, etc.
Any method call on the resulting proxy object will be automatically translated into a remote call to the service using
the provided configuration.
[source,java]
.Example
----
include::{sourcedir}/mp/RestclientSnippets.java[tag=snippet_1, indent=0]
----
The `RestClientBuilder` interface extends the `Configurable` interface from Jakarta REST (JAX-RS),
enabling direct registration of _providers_ such as filters, param converters, exception mappers, etc.
[source,java]
.Example
----
include::{sourcedir}/mp/RestclientSnippets.java[tag=snippet_2, indent=0]
----
=== Creating a New Client Using CDI
A client interface can be annotated with `@RegisterRestClient` to automatically register it with CDI.
This annotation has a property called `baseUri` that can be used to define the base endpoint to be used by the client
to access the service.
[source,java]
.Example
----
include::{sourcedir}/mp/RestclientSnippets.java[tag=snippet_3, indent=0]
----
Any Jakarta REST (JAX-RS) providers for a client can be registered using the (repeatable)
`@RegisterProvider` annotation on the interface as shown below.
[source,java]
.Example
----
include::{sourcedir}/mp/RestclientSnippets.java[tag=snippet_4, indent=0]
----
Once a client interface is annotated, it can be injected into any CDI bean.
All properties in annotation `RegisterRestClient` can be overridden via configuration as described in
<>
[source,java]
.Example
----
include::{sourcedir}/mp/RestclientSnippets.java[tag=snippet_5, indent=0]
----
== Configuration
Configuration is only available for CDI managed client instances, it is not supported for client created
programmatically using `RestClientBuilder`.
Most of the configuration properties mentioned below have to be prepended with the fully qualified classname of the
client interface to be configured.
It is possible to avoid fully qualified classname by using `@RegisterRestClient(configKey="clientAlias")`, the
prefix `$restClient` is used below to indicate an alias or a class name.
=== Configuration options
Required configuration options:
[cols="3,3,2,5"]
|===
|key |type |default value |description
|`$restClient/mp-rest/url` |string |{nbsp} |Sets the base URL to use for this service. This option or `/mp-rest/uri` need to be set if the value is not present in `RegisterRestClient#baseUri`.
|`$restClient/mp-rest/uri` |string |{nbsp} |Sets the base URI to use for this service. This option or `/mp-rest/url` need to be set if the value is not present in `RegisterRestClient#baseUri`.
|===
Optional configuration options:
[cols="3,3,2,5"]
|===
|key |type |default value |description
|`$restClient/mp-rest/scope` |string |`jakarta.enterprise.context.Dependent` |The fully qualified classname to a CDI scope to use for injection.
|`$restClient/mp-rest/connectTimeout` |long |{nbsp} |Sets timeout in milliseconds to wait to connect to the remote endpoint.
|`$restClient/mp-rest/readTimeout` |long |{nbsp} |Sets timeout in milliseconds to wait for a response from the remote endpoint.
|`$restClient/mp-rest/followRedirects` |boolean |`false` |Sets value used to determine whether the client should follow HTTP redirect responses.
|`$restClient/mp-rest/proxyAddress` |string |{nbsp} |Sets a string value in the form of : that specifies the HTTP proxy server hostname (or IP address) and port for requests of this client to use.
|`$restClient/mp-rest/queryParamStyle` |string (MULTI_PAIRS, COMMA_SEPARATED, ARRAY_PAIRS) |`MULTI_PAIRS` |Sets enumerated type string value that specifies the format in which multiple values for the same query parameter is used.
|`$restClient/mp-rest/trustStore` |string |{nbsp} |Sets the trust store location. Can point to either a classpath resource (e.g. classpath:/client-truststore.jks) or a file (e.g. file:/home/user/client-truststore.jks).
|`$restClient/mp-rest/trustStorePassword` |string |{nbsp} |Sets the password for the trust store.
|`$restClient/mp-rest/trustStoreType` |string |`JKS` |Sets the type of the trust store.
|`$restClient/mp-rest/keyStore` |string |{nbsp} |Sets the key store location. Can point to either a classpath resource (e.g. classpath:/client-keystore.jks) or a file (e.g. file:/home/user/client-keystore.jks).
|`$restClient/mp-rest/keyStorePassword` |string |{nbsp} |Sets the password for the keystore.
|`$restClient/mp-rest/keyStoreType` |string |`JKS` |Sets the type of the keystore.
|`$restClient/mp-rest/hostnameVerifier` |string |{nbsp} |Sets the hostname verifier class. This class must have a public no-argument constructor.
|===
Configuration options affecting CDI and programmatically created clients:
[cols="3,3,2,5"]
|===
|key |type |default value |description
|`$restClient/mp-rest/providers` |string |{nbsp} |A comma separated list of fully-qualified provider classnames to include in the client.
|`$restClient/mp-rest/providers//priority` |string |{nbsp} |Sets the priority of the provider for this interface.
|`org.eclipse.microprofile.rest.client.propagateHeaders` |string |{nbsp} |To specify which headers to propagate from the inbound JAX-RS request to the outbound MP Rest Client request. Should not be prefixed with the rest client class or alias.
|`microprofile.rest.client.disable.default.mapper` |boolean |`false` |Whether to disable default exception mapper. Should not be prefixed with the rest client class or alias.
|===
== Examples
To be able to run and test this example, use the xref:guides/quickstart.adoc[Helidon MP examples/quickstarts].
Add a dependency on the Helidon Rest Client implementation and create the following client interface:
[source,java]
.client interface
----
include::{sourcedir}/mp/RestclientSnippets.java[tag=snippet_6, indent=0]
----
Then create a runnable method as described in <>, but with baseUri
`http://localhost:8080/greet` and the above interface.
By calling `GreetRestClient.getDefaultMessage()` you reach the endpoint of Helidon quickstart.
== Reference
* link:{mp-restclient-javadoc-base-url}/module-summary.html[Helidon MicroProfile RestClient JavaDoc]
* link:{microprofile-rest-client-spec-url}[MicroProfile RestClient Specification]
* link:https://github.com/eclipse/microprofile-rest-client[MicroProfile RestClient on GitHub]
© 2015 - 2025 Weber Informatics LLC | Privacy Policy