-
Notifications
You must be signed in to change notification settings - Fork 2.6k
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.
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
Add REST Client guide #791
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@geoand nice work. I added a few comments inline, we should be there soon!
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>
.
|
6a3b48d
to
b96e6fd
Compare
@gsmet PR updated per your comments. Thanks for the thorough review! |
b96e6fd
to
f42c809
Compare
@geoand could you take a look at my latest commit? If you're OK with it, I'll merge it. |
Sure thing, checking now |
@gsmet Looks great! |
@geoand no worries, it makes the reviews useful and I really appreciate your work in general :). |
I'm very glad to help out :) |
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. |
I will keep an eye out for that work |
The corresponding quickstart is in a PR which is pending some fixes in shamrock itself