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.

---