Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document RestResponse #43759

Merged
merged 1 commit into from
Oct 8, 2024
Merged

Document RestResponse #43759

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
117 changes: 83 additions & 34 deletions docs/src/main/asciidoc/rest-client.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -337,8 +337,91 @@
* `File`
* `Path`

=== Getting other response properties

Check warning on line 340 in docs/src/main/asciidoc/rest-client.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Headings] Use sentence-style capitalization in 'Using RestResponse'.

Raw Output:
{"message": "[Quarkus.Headings] Use sentence-style capitalization in 'Using RestResponse'.", "location": {"path": "docs/src/main/asciidoc/rest-client.adoc", "range": {"start": {"line": 340, "column": 34}}}, "severity": "INFO"}

==== Using RestResponse

Check warning on line 342 in docs/src/main/asciidoc/rest-client.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'need to'.

Raw Output:
{"message": "[Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'need to'.", "location": {"path": "docs/src/main/asciidoc/rest-client.adoc", "range": {"start": {"line": 342, "column": 22}}}, "severity": "INFO"}

If you need to get more properties of the HTTP response than just the body, such as the status code
or headers, you can make your method return `org.jboss.resteasy.reactive.RestResponse` from a method.
An example of this could look like:

[source,java]
----
package org.acme.rest.client;

import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import org.jboss.resteasy.reactive.RestQuery;
import org.jboss.resteasy.reactive.RestResponse;

import java.util.Set;

@Path("/extensions")
@RegisterRestClient
public interface ExtensionsService {

@GET
RestResponse<Set<Extension>> getByIdResponseProperties(@RestQuery String id);
}
----

NOTE: You can also use the Jakarta REST type link:{jaxrsapi}/jakarta/ws/rs/core/Response.html[`Response`] but it is
not strongly typed to your entity.

== Create the Jakarta REST resource

Create the `src/main/java/org/acme/rest/client/ExtensionsResource.java` file with the following content:


[source,java]
----
package org.acme.rest.client;

import org.eclipse.microprofile.rest.client.inject.RestClient;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import java.util.Set;

@Path("/extension")
public class ExtensionsResource {

@RestClient // <1>
ExtensionsService extensionsService;


@GET
@Path("/id/{id}")
public Set<Extension> id(String id) {
return extensionsService.getById(id);
}

@GET
@Path("/properties")
public RestResponse<Set<Extension>> responseProperties(@RestQuery String id) {
RestResponse<Set<Extension>> clientResponse = extensionsService.getByIdResponseProperties(id); //<2>
String contentType = clientResponse.getHeaderString("Content-Type");
int status = clientResponse.getStatus();
String setCookie = clientResponse.getHeaderString("Set-Cookie");
Date lastModified = clientResponse.getLastModified();

Log.infof("content-Type: %s status: %s Last-Modified: %s Set-Cookie: %s", contentType, status, lastModified,
setCookie);

return RestResponse.fromResponse(clientResponse);
}
}
----

There are two interesting parts in this listing:

<1> the client stub is injected with the `@RestClient` annotation instead of the usual CDI `@Inject`
<2> `org.jboss.resteasy.reactive.RestResponse` used as effective way of getting response properties via RestResponse directly from RestClient,

Check warning on line 421 in docs/src/main/asciidoc/rest-client.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.", "location": {"path": "docs/src/main/asciidoc/rest-client.adoc", "range": {"start": {"line": 421, "column": 42}}}, "severity": "INFO"}

Check warning on line 421 in docs/src/main/asciidoc/rest-client.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsWarnings] Consider using 'through', 'by', 'from', 'on', or 'by using' rather than 'via' unless updating existing content that uses the term.

Raw Output:
{"message": "[Quarkus.TermsWarnings] Consider using 'through', 'by', 'from', 'on', or 'by using' rather than 'via' unless updating existing content that uses the term.", "location": {"path": "docs/src/main/asciidoc/rest-client.adoc", "range": {"start": {"line": 421, "column": 90}}}, "severity": "WARNING"}
as described in <<Using RestResponse>>

== Create the configuration

Check warning on line 424 in docs/src/main/asciidoc/rest-client.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsWarnings] Consider using 'to' rather than 'In order to' unless updating existing content that uses the term.

Raw Output:
{"message": "[Quarkus.TermsWarnings] Consider using 'to' rather than 'In order to' unless updating existing content that uses the term.", "location": {"path": "docs/src/main/asciidoc/rest-client.adoc", "range": {"start": {"line": 424, "column": 19}}}, "severity": "WARNING"}

Check warning on line 424 in docs/src/main/asciidoc/rest-client.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Fluff] Depending on the context, consider using 'Be concise: use 'to' rather than' rather than 'In order to'.

Raw Output:
{"message": "[Quarkus.Fluff] Depending on the context, consider using 'Be concise: use 'to' rather than' rather than 'In order to'.", "location": {"path": "docs/src/main/asciidoc/rest-client.adoc", "range": {"start": {"line": 424, "column": 19}}}, "severity": "INFO"}

In order to determine the base URL to which REST calls will be made, the REST Client uses configuration from `application.properties`.
The name of the property needs to follow a certain convention which is best displayed in the following code:
Expand Down Expand Up @@ -411,40 +494,6 @@
quarkus.rest-client.extensions-api.alpn=true
----

== Create the Jakarta REST resource

Create the `src/main/java/org/acme/rest/client/ExtensionsResource.java` file with the following content:


[source,java]
----
package org.acme.rest.client;

import org.eclipse.microprofile.rest.client.inject.RestClient;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import java.util.Set;

@Path("/extension")
public class ExtensionsResource {

@RestClient // <1>
ExtensionsService extensionsService;


@GET
@Path("/id/{id}")
public Set<Extension> id(String id) {
return extensionsService.getById(id);
}
}
----

There are two interesting parts in this listing:

<1> the client stub is injected with the `@RestClient` annotation instead of the usual CDI `@Inject`

== Programmatic client creation with QuarkusRestClientBuilder

Instead of annotating the client with `@RegisterRestClient`, and injecting
Expand Down