justineechen
commented
6 years ago Testing the service
- The directories for the path src/test/java/it/io/openliberty/guides/rest/ could be created in the starter file so the user only needs to cd to rest and create EndpointTest.java
What you'll learn
[x] "When you create a new REST application the design of the API is important. The JAX-RS APIs could be used to create JSON-RPC, or XML-RPC APIs, but wouldn’t be a RESTful service. A good RESTful service is designed around the resources that are exposed, and how to create, read, update, and delete the resources." -> hard to understand what this paragraph is trying to convey. Why wouldn't that be a restful service, etc.? Also some grammar mistakes
[x] "The service responds to GET requests to the /System/properties path. The GET request should return a 200 OK response that contains all of the JVM’s system properties." -> is this really needed?
Creating a JAX-RS application
a diagram to demonstrate how resource classes connect to the application class (discussion and design required. Perhaps an extra item for now).
~"Create the JAX-RS application class in the src/main/java/io/openliberty/guides/rest/SystemApplication.java file:" should be just "Create"~
[x] "...making them available under the common path specified in the SystemApplication class." -> change to "...making the available under the common path specified in the @ApplicationPath annotation"
Creating the JAX-RS resource
~"Create the JAX-RS resource class in the src/main/java/io/openliberty/guides/rest/PropertiesResource.java file:" -> should be "Create"~ (n/a - already addressed).
~PropertiesResource.java has unused imports~ (n/a - already addressed).
[x] the code snippet is pretty small so I dont think there is need to break it up when explaining what the code does (would argue that its a benefit of the guide being an "intro"
[x] "JAX-RS maps the HTTP methods on the URL to the methods on the class. The method to call is determined by the annotations specified on the methods. In the application you are building, an HTTP GET request to the System/properties path results in the system properties being returned:" -> needs rewording, its not very clear. All we're trying to say that HTTP request methods like GET/POST are mapped to Java methods using appropriate annotations. And then say something like use the @GET annotation to map ...
~"JAX-RS supports a number of ways to marshal JSON. The JAX-RS 2.0 specification mandates JSON-Processing (JSON-P) and JAX-B. Most JAX-RS implementations also support a Java POJO-to-JSON conversion, which allows the Properties object to be returned instead. Although this conversion would allow for a simpler implementation, it limits code portability as POJO-to-JSON conversion is non-standard. This gap in the specification will be fixed in Java EE 8 with the inclusion of JSON-B." -> is extra, should probably be removed~ (n/a - already addressed).
[x] "The method body does the following actions:" -> perhaps we can convert this whole part into comments in the code directly? It would certainly shorten down the whole guide
Building the application
~"To build the application, run the following command:" -> "To build the application, run the Maven install goal:"~ (n/a - already addressed).
~"This command builds the application and creates a .war file in the target directory. The command also configures and installs Liberty into the target/liberty/wlp directory. After the Maven build completes, you can use the server script in that Liberty installation. You can also start and stop the server by using the Maven goals of liberty:start-server and liberty:stop-server." -> needs rewording~ (n/a - already addressed).
~"If the server is running, running the installation can cause issues because the installation attempts to start a server. You can instead run the following command:" -> reword to be something like "To rebuild the application without restarting the server, run the Maven package goal. This goal will ... Note that running install when the server is running will cause issues " or something like that~ (n/a - already addressed).
~"If you use a tool that does incremental updates, like Eclipse, then you can bypass the application build." -> perhaps mention WDT?~ (n/a - already addressed).
Testing the service
[x] "You could test this service manually by starting a server and pointing a web browser at the http://localhost:9080/LibertyProject/System/properties URL. Automated tests are a much better approach because they will trigger a failure if a change introduces a bug. JUnit and the JAX-RS Client API provide a very simple environment to test the application." -> needs some sentence connectors (paragraph seems unnecessary now)
~the part with server.xml seems to be off place. Should we talk about it at all or just provide the complete one? Perhaps it might be a good idea to write a guide on how to configure OL. In any case, this section should definitely not be under the tests~ (n/a - already addressed).
~continuing from the above, should we go into detail about how the pom.xml is configured? I dont think we need the section "The variables being used in the server.xml file are provided by the bootstrapProperties section of the Maven pom.xml:"~ (n/a - already addressed).
Great work! You’re done!