Defining our To Do service endpoints in JavaEE

In the previous blog post, we got our JavaEE project up and running and created a very simple REST endpoint. In this post, we’ll talk a bit more about what data we expect to handle and how we’ll interact with our service.

The first thing we will talk about is the data object. We know we’re building a “to do” service. Our “to do” elements will be very simple. They’ll only contain a description. In addition to the description, they’ll need a unique identifier, or an “id”. Pretty straight forward. Go ahead and create a “Todo.java” file and paste the following into it:

public class Todo {
	private Long id;
	private String description;

	public Long getId() {
		return id;
	}

	public void setId(Long id) {
		this.id = id;
	}

	public String getDescription() {
		return description;
	}

	public void setDescription(String description) {
		this.description = description;
	}
}

The next thing we’ll need to figure out is how we expect our users to interact with our service.

When the user first opens up the screen, they should see a list of all of the “to do” items. They should also be able to update, create, and delete existing entries too. This means there are four actions and thus, four endpoints.

Open the TodoService.java file we created in the last post and paste the following:

@Path("/")
public class TodoService {
	@GET
	@Produces(MediaType.APPLICATION_JSON)
	public List getAll() {
		return null;
	}

	@POST
	@Consumes(MediaType.APPLICATION_JSON)
	public void create(Todo incoming) {
	}

	@PUT
	@Path("{id}")
	@Consumes(MediaType.APPLICATION_JSON)
	public void update(@PathParam("id") Long id, Todo incoming) {
	}

	@DELETE
	@Path("{id}")
	public void remove(@PathParam("id") Long id) {
	}
}

The first method, “getAll” is the endpoint that will be invoked when the user first opens the application. Since the plan is to build a web-application, returning data in JSON format makes the most sense. And we annotate it with @GET because we want it to respond to GET requests. Note that since there is no @Path annotation on this method that it inherits the @Path annotation set for the class.

The second method, “create” is how the user will create entries. We use the @POST annotation since, in REST, POST is used to create objects. This isn’t set in stone, but it is a good rule of thumb to follow. Instead of returning JSON, this endpoint will read JSON from the HTTP request body and map it to our data object we just defined.

The third method, “update” is how the user will update their entries. According to REST, PUT is used when we want to update existing objects and you also add the id of the object on the path. In order to access this method, the caller will need to pass in the id of the entry they want to update. For example PUT http://localhost:8080/todo/1 with the new JSON in the request body. The @PathParam annotation ties a method parameter to a parameter defined within @Path.

The fourth method, “remove” is straightforward. It’s used when the user wants to remove an entry and the caller will use the DELETE HTTP method to invoke it.

That’s it for this post, we really just wanted to define the API that we’ll be implementing in future posts.

In the next post we’ll set up a datasource, which is where we’ll store our data.

Source code is available here: