Building JSON REST API endpoints with Play Framework 2.6 and Java

In this tutorial, you will learn how to build a RESTful API with Play 2.6 and Java 8 in four easy steps.

This tutorial assumes that you have used at least one backend framework for building web applications.

Steps:
1. Defining Endpoints
2. Getting Play up and running
3. Building the endpoints
4. Testing the endpoints

Step 1 - Defining Endpoints

The entity we will be working on will be a Book. Every book will have a title, a description, and an Authors Name.

At the end we will have 5 endpoints for our application:
GET /books
GET /book/{id}
PUT /book/{id}
POST /book/{id}
DELETE /book/{id}

Step 2 - Getting Play up and running

Download the empty Play app I've set up for this project by clicking here.

Once you have downloaded the project extract its contents into a folder play-rest-book. This app is different than the default Play Java App because it contains JSON library as a dependency. Start the server by running "sbt run" command from your terminal like on the image below.

The server will automatically pick up any changes to the code.

Now that we have our Play application setup it is time to start working on our RESTful endpoints.

Step 3 - Building the endpoints

The app will consist of Controllers, Repositories, and Models.

Models - Plain old java object that will be mapping out data. For us, this will be a Book.

Repositories - Encapsulate access to our Data. Will have methods like find, remove etc...

Controllers - Handle client requests.

This project is based on the pod structure.

To get started let's make separate folders for models, repositories and controllers in our /app directory. In this folders we will define 3 classes Book (in models), BookController (in controllers) and a BookRepository (in repositories).

After creating these classes your project structure should be like on the image below:

Book Class is representing our Model and is a simple POJO with fields we have defined previously. Code for Book.java can be seen below.

BookRepository Class is representing our Data store and it will be a Play singletone component. What this means is that Play will make exactly one instance of this repository per application. To do this we have to mark our class with Singleton annotation. In the next post we will be adding database connection to this class.

BookController Class is representing our interface to the web. It will contain methods that will be mapped to routes that users can call. This class will be extending Plays play.mvc.Controller.

Our Controller should have one method per endpoint, so it will have 5 methods. Every method will be returning an instance of Plays play.mvc.Result that Play will convert into a proper HTTP response for us. To generate Result objects we will be using methods from play.mvc.Controler.

Here you can see how your Controller should look like:

The last step of configuring the app is filling out the routes file. This file defines which route should call which Controller method. This is done in the /conf/routes file. This file contains 3 parts separated by any number of spaces.

Here is how our routes file should look like:

And that's it, with these 4 files we have built a complete set of endpoints for dealing with Books.

Step 4 - Testing the endpoints

To test our endpoints we will use the Postman app. This app will allow us to build simple requests and test our API.

Here you can see print screens of Postman I've used to test the endpoints.

Testing POST /book/{id} show
Testing GET /books show
Testing GET /book/{id} show
Testing PUT /book/{id} show
Making sure PUT worked show
Testing DELETE /book/{id} show
Making sure DELETE worked show

Conclusion

Hi, thanks for following this through!

If you would like to add MySQL database to this application click here.

If you have any comments or suggestions please leave a comment or contact me at dusan.stanojevic.cs@gmail.com

The final code for this project can be found here.

Author

Dusan Stanojevic Dux

Hi, I'm a full stack developer. I've been programming for over 5 years. I use Javascript, Java, Objective C and C++ on a daily. I love driving cars and playing the guitar.