Add REST Client guide

[geoand]

The corresponding quickstart is in a PR which is pending some fixes in shamrock itself

[gsmet]

@geoand nice work. I added a few comments inline, we should be there soon!

[geoand]

No problem, I will address all the concerns tomorrow and update the PR

…

On Thu, Feb 7, 2019, 20:16 Guillaume Smet ***@***.*** wrote: ***@***.**** commented on this pull request. @geoand <https://github.com/geoand> nice work. I added a few comments inline, we should be there soon! ------------------------------ In docs/src/main/asciidoc/rest-client-guide.adoc <#791 (comment)> : > + + +== Setting up the model + +In this guide we will be demonstrating how to consume part of the REST API supplied by the https://restcountries.eu service. +Our first order of business to setup the part of the model we will be using, which is that of a `Country`. + +Create a `src/main/java/org/acme/restclient/Country.java` file and set the following content: + +[source,java] +---- +package org.acme.restclient; + +import java.util.List; + +public class Country { So... about this one... I nearly asked the question when I reviewed the quickstart but now I can't avoid it: would it be possible to only have a few fields that make sense here and not the whole thing? I don't know if the serialization will throw an exception or just ignore the missing fields? ------------------------------ In docs/src/main/asciidoc/rest-client-guide.adoc <#791 (comment)> : > +Clone the Git repository: `git clone https://github.com/jbossas/protean-quickstarts.git` <https://github.com/jbossas/protean-quickstarts.git>, or download an https://github.com/jbossas/protean-quickstarts/archive/master.zip[archive]. + +The solution is located in the `rest-client` directory. + +== Creating the Maven project + +First, we need a new project. Create a new project with the following command: + +[source, subs=attributes+] +---- +mvn org.jboss.shamrock:shamrock-maven-plugin:{shamrock-version}:create \ + -DprojectGroupId=org.acme \ + -DprojectArtifactId=rest-client \ + -DclassName="org.acme.restclient.CountriesResource" \ + -Dpath="/country" \ + -Dextensions="rest-client" The jaxrs and jaxrs-json extensions are imported automatically? ------------------------------ In docs/src/main/asciidoc/rest-client-guide.adoc <#791 (comment)> : > +[source, subs=attributes+] +---- +mvn org.jboss.shamrock:shamrock-maven-plugin:{shamrock-version}:create \ + -DprojectGroupId=org.acme \ + -DprojectArtifactId=rest-client \ + -DclassName="org.acme.restclient.CountriesResource" \ + -Dpath="/country" \ + -Dextensions="rest-client" +---- + +This command generates the Maven project with a REST endpoint and imports the `rest-client` extension. + + +== Setting up the model + +In this guide we will be demonstrating how to consume part of the REST API supplied by the https://restcountries.eu service. Let's make it a link to the service. ------------------------------ In docs/src/main/asciidoc/rest-client-guide.adoc <#791 (comment)> : > +---- +mvn org.jboss.shamrock:shamrock-maven-plugin:{shamrock-version}:create \ + -DprojectGroupId=org.acme \ + -DprojectArtifactId=rest-client \ + -DclassName="org.acme.restclient.CountriesResource" \ + -Dpath="/country" \ + -Dextensions="rest-client" +---- + +This command generates the Maven project with a REST endpoint and imports the `rest-client` extension. + + +== Setting up the model + +In this guide we will be demonstrating how to consume part of the REST API supplied by the https://restcountries.eu service. +Our first order of business to setup the part of the model we will be using, which is that of a `Country`. Our first order of business *is* to setup ------------------------------ In docs/src/main/asciidoc/rest-client-guide.adoc <#791 (comment)> : > +import javax.ws.rs.PathParam; +import javax.ws.rs.Produces; +import java.util.Set; + ***@***.***("/v2") ***@***.*** +public interface CountriesService { + + @get + @path("/name/{name}") + @produces("application/json") + Set<Country> ***@***.***("name") String name); +} +---- + +The `getByName` method gives our code the ability to query a country from the restcountries.eu API by name. The client with handle all the networking and mashalling leaving our code clean of such technical details. s/mashalling/marshalling/ ------------------------------ In docs/src/main/asciidoc/rest-client-guide.adoc <#791 (comment)> : > +import javax.ws.rs.PathParam; +import javax.ws.rs.Produces; +import java.util.Set; + ***@***.***("/v2") ***@***.*** +public interface CountriesService { + + @get + @path("/name/{name}") + @produces("application/json") + Set<Country> ***@***.***("name") String name); +} +---- + +The `getByName` method gives our code the ability to query a country from the restcountries.eu API by name. The client with handle all the networking and mashalling leaving our code clean of such technical details. I think adding a paragraph about the annotations would be nice: - @RegisterRestClient - clearly states the url of the service and thus the @path annotations - the fact that in {project-name}, it's really importante to set the Produces/Consumes annotations so that we can narrow down the classes included in the native image. (note that this is not implemented yet but it should be soon so let's do as it was) ------------------------------ In docs/src/main/asciidoc/rest-client-guide.adoc <#791 (comment)> : > + + @Inject + @restclient + private CountriesService countriesService; + + + @get + @path("/name/{name}") + @produces(MediaType.APPLICATION_JSON) + public Set<Country> ***@***.***("name") String name) { + return countriesService.getByName(name); + } +} +---- + +Note that we in addition to the standard CDI ***@***.***` annotation, we also need to use the MicroProfile ***@***.***` annotation to inject `CountriesService`. Note that we in -> Note that in ------------------------------ In docs/src/main/asciidoc/rest-client-guide.adoc <#791 (comment)> : > + + + @get + @path("/name/{name}") + @produces(MediaType.APPLICATION_JSON) + public Set<Country> ***@***.***("name") String name) { + return countriesService.getByName(name); + } +} +---- + +Note that we in addition to the standard CDI ***@***.***` annotation, we also need to use the MicroProfile ***@***.***` annotation to inject `CountriesService`. + +== Update the test + +We also need to update the functional test to reflect the changes made to endpoint. made to endpoint -> made to the endpoint ------------------------------ In docs/src/main/asciidoc/rest-client-guide.adoc <#791 (comment)> : > + public void testCountryNameEndpoint() { + given() + .when().get("/country/name/greece") + .then() + .statusCode(200) + .body("$.size()", is(1), + "[0].alpha2Code", is("GR"), + "[0].capital", is("Athens"), + "[0].currencies.size()", is(1), + "[0].currencies[0].name", is("Euro") + ); + } + +} +---- + Maybe add a sentence explaining we are using the json-path assertions provided by REST Assured. ------------------------------ In docs/src/main/asciidoc/rest-client-guide.adoc <#791 (comment)> : > + "[0].alpha2Code", is("GR"), + "[0].capital", is("Athens"), + "[0].currencies.size()", is(1), + "[0].currencies[0].name", is("Euro") + ); + } + +} +---- + +== Package and run the application + +Run the application with: `mvn compile shamrock:dev`. +Open your browser to http://localhost:8080/country/name/greece. + +You should see a rather large JSON output Hopefully, we will make it a bit smaller ;). ------------------------------ In docs/src/main/asciidoc/rest-client-guide.adoc <#791 (comment)> : > @@ -0,0 +1,600 @@ += {project-name} - Using the REST Client + +This guide explains how to use the MicroProfile REST Client in order to interact with REST APIs +with very little effort. + +== Prerequisites + +To complete this guide, you need: + +* between 5 and 10 minutes let's say 10 to 15, as you need to read and understand the content :) — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#791 (review)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AELBv8aryTZ1A0VZh1KtYQN9BWZHxZ3Fks5vLG1ygaJpZM4anDYu> .

[geoand]

@gsmet PR updated per your comments.

Thanks for the thorough review!

[gsmet]

@geoand could you take a look at my latest commit? If you're OK with it, I'll merge it.

[geoand]

@geoand could you take a look at my latest commit? If you're OK with it, I'll merge it.

Sure thing, checking now

[geoand]

@gsmet Looks great!
As you have noticed I am always making stupid grammar mistakes because I'm thinking ahead of what I write :(. So thank you very much for catching them!

[gsmet]

@geoand no worries, it makes the reviews useful and I really appreciate your work in general :).

[geoand]

@geoand no worries, it makes the reviews useful and I really appreciate your work in general :).

I'm very glad to help out :)

[gsmet]

And merged, thanks. I will make some additional adjustments once @kenfinnigan has finished his work on the SmallRye REST client and has integrated it in Shamrock.

It should work the same way but we should advertise the fact that we will be using SmallRye REST client.

[geoand]

I will keep an eye out for that work