Sample java play project to go with the play-rest-workshop slides.

In this exercise you will implement a simple RESTful API for providing access to user information.
The User model is provided in User.java.
A GET endpoint for retrieving all users is provided. Go to http://localhost:9000/users to see the list of all users. Currently it’s empty.

Example exercises are provided below (duplicated from the workshop slides).

Exercise 1

Add a POST endpoint for creating a new user with id and username specified in the request body in json format.
Create 3 new users using curl with ids 1-3.

curl -vX POST http://localhost:9000/users -d '{"name":"John", "id":1}' --header "Content-Type: application/json"

What code should be returned in the response header on success?

Exercise 1 cont’d

Check http://localhost:9000/users again to see all the users you added.
What happens when you try to POST with a non-integer user id or with the id missing entirely?

What code should be returned in the response header?

Exercise 1 JUnit Tests

Add tests to ApplicationTest.java to test for
- Successful user creation
- Bad parameter data

Exercise 2

Add a GET endpoint for retrieving a user with a specific id.
- Try manually checking that your endpoint works correctly using your web browser.
- What code should be returned in the response header on success?
- What code should be returned when the user does not exist?
- What code should be returned when you request a non-integer user id?

Exercise 2 JUnit Tests

Add tests to ApplicationTest.java to test for
- Successful user retrieval
- User not found

Exercise 3

Add a PUT endpoint for updating a specific user. This time accept the id parameter in the path and the name parameter as form-encoded.

Use curl to update the name of any user.

curl -vX POST http://localhost:9000/users/1 -d "name=John" --header "Content-Type: application/json"

Exercise 3 JUnit Tests

Add tests to ApplicationTest.java to test for
- Successful user update
- User not found

Exercise 4

Let’s say that DELETE requests are not allowed. Try using curl to delete a user with a specific id. What response do you get?
Write a handler for the DELETE endpoint so that you return a 405 Method Not Allowed error code.

Exercise 4 JUnit Tests

Add a test to ApplicationTest.java to make sure 405 is returned for DELETE requests.

Exercise 5: Api docs with Swagger

Add the following line to the libraryDependencies in build.sbt

"pl.matisoft" %% "swagger-play24" % "1.4"

Add annotations to your handlers in Application.java

http://docs.swagger.io/swagger-core/apidocs/index.html

Exercise 5 cont'd

Modify routes file to provide endpoints for documentation

GET /api-docs.json @pl.matisoft.swagger.ApiHelpController.getResources

GET /api-docs.json/users @pl.matisoft.swagger.ApiHelpController.getResource(path = "/users")

Now you can see your api documentation as json at http://localhost:9000/api-docs.json http://localhost:9000/api-docs.json/users

Exercise 5 Swagger UI

Add Swagger UI to get a human-friendly format for the json docs.

git clone https://github.com/swagger-api/swagger-ui

Copy contents of dist folder to your public folder
Copy /public/swagger/index.html into your views folder and rename it swagger.scala.html
swagger.scala.html needs to be customized
- update all the static paths at the top of the file to prepend assets/swagger to the path (see link and script tags)
- search for new SwaggerUi and change the url to "http://localhost:9000/api-docs.json" instead of the petstore example url

Exercise 5: Swagger UI

Add a /swagger endpoint to your routes file and add the corresponding action to Application.java to render swagger.scala.html
Go to http://localhost:9000/swagger to see your formatted documentation.
Use your new Swagger documentation to test your api. Create new users and query users.

leerobert/rest-java-play-sample