Java RESTful Backend for an app about the Galaxy's finest smugglers (SW)

In this post, I aim to show how to build a Java RESTful web service or a Java Restful backend that can be used(consumed) by a mobile app or a web site. Unlike my pervious posts where I explain a technical solution, I am going to structure this one differently. In this one I am going to try and tell a developer's story through it.

Background

Our story picks up from the time Cpt.Danko (Danko) returns to work after being away for 3 months on medical leave. At this point all we know about Danko is that before going on leave he was just a developer, all he did was write code the way he was asked to and he had very little responsibility. On returning to work, he didn't realise that he was no longer just a developer but he was actually "promoted" to a full-stack developer and had heaps(lots) more responsibility with the same old (low) wage. This "promotion" caught him by surprise as after being away for 3 months he expected to have the same level of responsibility as before, instead he had a lot more responsibility and he was part of a much smaller team. However he was a fan of X-Men and particularly of Darwin, so like one of this favourite superheroes, he believed he must adapt to survive and so he stayed on the job. A year later he fell in love with this new role and his new project at which point he appreciated his decision to stay on the job.

What was Danko's new project about?

For his new project, Danko was asked to build an app that

• that shows a list of some of the galaxy's finest smugglers 
• their race when we click on them 
• and the user should also have the ability to add a smuggler

Since this was a client project, the UI for the project was already known and the first thing that Danko had to do was to create the backend i.e. the RESTful backend.

Limitations

Danko was asked to build the backend in Java because,

1. he had a lot of experience working with Java
2. his workplace already had a team of experienced Java developers who could maintain the app when he wasn't around

Ohh and the team were experienced in working with Jersey so even though he had little experience using Jersey, he needed to use it to build a RESTful web service.

Choice of Java IDE

Those limitations aside Danko had the freedom to choose whichever Java IDE he preferred  to build the system and since he had prior experience working with Eclipse, he decided to use it and set out to build the system.

Building the solution

Unlike his previous role, he was now a full-stack developer so he was just given a problem for which he had to do some analysis and think about the backend structure i.e. models etc. Since the first version of the app was going to be really basic, he thought the backend will will only need to,

1. to send the list of smugglers to the app front-end
2. receive the id of the smuggler and send some info about their race
3. accept some information to be able to add a new smuggler

Since Danko knew Java, he thought the above requirements translate to these simple Java methods, which would be part of an interface i.e. SmugglerService.

public List<Smuggler> getSmugglers();

public String smugglerRace(int id);

public void addSmuggler(Smuggler smuggler); 

After his initial analysis, he started building the actual backend,

1. He created a new Dynamic Web project in Eclipse
2. Created the packages 
1. com.app.models
2. com.app.services
3. Added the jersey libs to the project
4. Followed by adding a reference to those libs to his project classpath
5. And finally added info about the Jersey servlet to the deployment descriptor (web.xml)

The next step was to define the model i.e. the Smuggler class, so he added com.app.models.Smuggler.java to the models package. For the first version he made it such that a Smuggler will only have a name, lastname and an id.

public class Smuggler {
    private String name;
    private String lastname;
    private int id;
    public Smuggler() {

    }
    public Smuggler(int id, String name, String lastname) {
        this.id = id;
        this.name = name;
        this.lastname = lastname;
    }
    //Generate getters and setters using Eclipse
}

The next task was to use Jersey to make a Java RESTful backend and remember as we mentioned before, Danko had little or no experience working with Jersey. So he did a quick Google search to learn more about Jersey and he gained the most out the links belo,

1. Jersey official tutorial
2. REST with Java (JAX-RS) using Jersey - Tutorial
3. Jax-RS tutorial

Jersey is about annotations and on realising that he decided that he should try and learn as much as he can about how to use annotations such as @GET, @POST, @Path, @Produces etc. Now based on his new found knowledge about Jersey and it's annotations, he added the class com.app.services.SmugglerServiceImpl.java, which would implement the SmugglerService interface.

package com.app.services;

import java.util.ArrayList;
import java.util.List;

import javax.ws.rs.GET;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

import com.app.models.Smuggler;

@Path("smuggler")
public class SmugglerServiceImpl implements SmugglerService{

    private Smuggler hondo = new Smuggler(1, "Hondo","Ohnaka");
    private Smuggler han = new Smuggler(2, "Han","Solo");

    @GET
    @Path("all")
    @Produces(MediaType.APPLICATION_JSON)
    public List<Smuggler> getAll() {
        List<Smuggler> smugglers = new ArrayList<Smuggler>();
        smugglers.add(hondo);
        smugglers.add(han);
        return smugglers;
    }

    @GET
    @Path("race/{id}")
    @Produces(MediaType.APPLICATION_JSON)
    public String smugglerRace(@PathParam("id") int id) {
        if(id == 1){
            return "Weequay";
        } else {
            return "Human";
        }
    }
    @POST
    @Path("new")
    public void addSmuggler(Smuggler smuggler) {
        System.out.println("new smuggler -> name"+ smuggler.getName()+", lastname:"+smuggler.getLastname());
    }
}

Danko's entire project source-code for the Smuggler's app backend can be found here on GitHub.

p.s. Remember that the initially what Danko was building was just proof of concept, so he just hard-coded certain things like the names of the smugglers.

How to run the project?

At this stage all he did was run the project from his Eclipse IDE. These were the tools used by Danko,

1. Eclipse Luna with WTP
2. Tomcat 7
3. Java 8: Although no specific Java 8 features were used in the code

Danko's work environment had people using both Mac and Windows machines so he had to get the project running on both Mac and Windows.

So to run Danko's project, download or clone it from Github and then when you run it from Eclipse, right-click on the project name and choose Run on Server and select Tomcat as your Server.

Once you have it running, then you can can access invoke some of the Smuggler service url's,

1. http://localhost:8080/AppBackend/REST/smuggler/all/ -> To get all the smugglers
2. http://localhost:8080/AppBackend/REST/smuggler/race/2/ -> Pass the smuggler id to get the race of the smuggler

Conclusion

At this point Danko had created an initial implementation of the REST backend that exposes certain resources ready to be consumed by an app or a website. We will pick up his story later and see how he goes about making an app that consumes these RESTful endpoints.

So for those reading this post, do you like the new approach i.e. my attempt to show how to build a solution by putting a story backdrop to it? My aim here is to choose a fun subject matter to make it a bit more interesting. The reason I added a character and a story to it is so that there's something that any programmer can relate to! Every now and then programmer's face new problems so with this story I aim to highlight just how would one go about solving a new problem. If I have missed anything or if I didn't quite achieve what I was trying to achieve here, it would be great if you leave a comment with some feedback - that would help me a lot.

Feedback points

I would appreciate some feedback on the following points,

1. The Star Wars reference for building the app backend is too immature?
2. Does adding a story backdrop doesn't fit well in the context of a technical post?
3. Does it lack sufficient technical details to build a Java REST backend?

Lastly, I am working on my app full-time right now and if you find my blog posts useful and want to support me you can 

• Either buy the Pro version of My Day To-Do

• Or give the Lite(free) version a try

You could also show your support by giving the My Day To-Do Facebook page a like.