Resource Identification

We begin the resource identification process by analyzing requirements and extracting nouns. At a high level, the QuickPoll application has users that create and interact with polls. From the previous statement, you can identify User and Poll as nouns and classify them as resources. Similarly, users can vote on polls and view the voting results, making Vote another resource. This resource modeling process is similar to database modeling in that it is used to identify entities or object-oriented design that identifies domain objects.

It is important to remember that all nouns identified need not be exposed as resources. For example, a poll contains several options, making Option another candidate for resource. Making Poll Option a resource would require a client to make two GET requests. The first request will obtain a Poll representation; the second request will obtain an associated Options representation. However, this approach makes the API chatty and might overload servers. An alternative approach is to include the options inside a Poll representation, thereby hiding Option as a resource. This would make Poll a coarse-grained resource, but clients would get poll-related data in one call. Additionally, the second approach can enforce business rules such as requiring at least two options for a poll to be created.

This noun approach allows us to identify collection resources. Now, consider the scenario in which you want to retrieve all of the votes for a given poll. To handle this, you need a “votes” collection resource. You can perform a GET request and obtain the entire collection. Similarly, we need a “polls” collection resource, which allows us to query groups of polls and create new ones.

Resource Representation

The next step in the REST API design process is defining resource representations and representation formats. REST APIs typically support multiple formats such as HTML, JSON, and XML. The choice of the format largely depends on the API audience. For example, a REST service that is internal to the company might only support JSON format, whereas a public REST API might speak XML and JSON formats. In this chapter and in the rest of the book, JSON will be the preferred format for our operations.

Now that we have defined our resource representation, we will move on to identifying endpoints for those resources.

Endpoint Identification

REST resources are identified using URI endpoints. Well-designed REST APIs should have endpoints that are understandable, intuitive, and easy to use. Remember that we build REST APIs for our consumers to use. Hence, the names and the hierarchy that we choose for our endpoints should be unambiguous to consumers.

We design the endpoints for our service using best practices and conventions widely used in the industry. The first convention is to use a base URI for our REST service. The base URI provides an entry point for accessing the REST API. Public REST API providers typically use a subdomain such as http://api.domain.com or http://dev.domain.com as their base URI. Popular examples include GitHub’s https://api.github.com and Twitter’s https://api.twitter.com. By creating a separate subdomain, you prevent any possible name collisions with webpages. It also allows you to enforce security policies that are different from the regular website. To keep things simple, we will be using http://localhost:8080 as our base URI in this book.

The second convention is to name resource endpoints using plural nouns. In our QuickPoll application, this would result in an endpoint http://localhost:8080/polls for accessing the Poll collection resource. Individual Poll resources will be accessed using a URI such as http://localhost:8080/polls/1234 and http://localhost:8080/polls/3456. We can generalize access to individual Poll resources using the URI template http://localhost:8080/polls/{pollId}. Similarly, the endpoints http://localhost:8080/users and http://localhost:8080/users/{userId} are used for accessing collection and individual User resources.

The third convention advises using a URI hierarchy to represent resources that are related to each other. In our QuickPoll application, each Vote resource is related to a Poll resource. Because we typically cast votes for a Poll, a hierarchical endpoint http://localhost:8080/polls/{pollId}/votes is recommended for obtaining or manipulating all the votes associated with a given Poll. In the same way, the endpoint http://localhost:8080/polls/{pollId}/votes/{voteId} would return an individual vote that was cast for the Poll.

Finally, the endpoint http://localhost:8080/computeresult can be used to access the ComputeResult resource. For this resource to function properly and count the votes, a poll id is required. Because the ComputeResult works with Vote, Poll, and Option resources, we can’t use the third approach for designing a URI that is hierarchal in nature. For use cases like these that require data to perform computation, the fourth convention recommends using a query parameter. For example, a client can invoke the endpoint http://localhost:8080/computeresult?pollId=1234 to count all of the votes for the Poll with id 1234. Query parameters are an excellent vehicle for providing additional information to a resource.

In this section, we have identified the endpoints for the resources in our QuickPoll application. The next step is to identify the actions that are allowed on these resources, along with the expected responses.

Action Identification

This concludes the design for the QuickPoll REST service. Before we start our implementation, we will review QuickPoll’s high-level architecture.

Domain Implementation

The domain objects typically act as a backbone for any application. So, the next step in our implementation process is to create domain objects. Figure 4-5 shows a UML Class diagram representing the three domain objects in our QuickPoll application and their relationships.

Repository Implementation

Repositories, or data access objects (DAO), provide an abstraction for interacting with datastores. Repositories traditionally include an interface that provides a set of finder methods such as findById, findAll for retrieving data, and methods to persist and delete data. Repositories also include a class that implements this interface using datastore-specific technologies. For example, a repository dealing with a database uses technology such as JDBC or JPA, and a repository dealing with LDAP would use JNDI. It is also customary to have one repository per domain object.

Although this has been a popular approach, there is a lot of boilerplate code that gets duplicated in each repository implementation. Developers attempt to abstract common functionality into a generic interface and generic implementation (http://www.ibm.com/developerworks/library/j-genericdao/). However, they are still required to create a pair of repository interfaces and classes for each domain object. Often these interfaces and classes are empty and just result in more maintenance.

Embedded Database

In the previous section, we created repositories, but we need a relational database for persisting data. The relational database market is full of options ranging from commercial databases such as Oracle and SQL Server to open-source databases such as MySQL and PostgreSQL. To speed up our QuickPoll application development, we will be using HSQLDB, a popular in-memory database. In-memory, aka embedded, databases don’t require any additional installations and can simply run as a JVM process. Their quick startup and shutdown capabilities make them ideal candidates for prototyping and integration testing. At the same time, they don’t usually provide a persistent storage and the application needs to seed the database every time it bootstraps.

API Implementation

In this section, we will create Spring MVC controllers and implement our REST API endpoints. We begin by creating the com.apress.controller package under srcmainjava to house all of the controllers.

PollController Implementation

The PollController provides all of the necessary endpoints to access and manipulate the Poll and Polls resources. Listing 4-14 shows a bare-bones PollController class .

package com.apress.controller;

import javax.inject.Inject;

import org.springframework.web.bind.annotation.RestController;

import com.apress.repository.PollRepository;

@RestController

public class PollController {

        @Inject

        private PollRepository pollRepository;

}

Listing 4-14

PollController Class

The PollController class is annotated with a @RestController annotation . The @RestController is a convenient yet meaningful annotation and has the same effect as adding both @Controller and @ResponseBody annotations. Because we need to read and store Poll instances, we use the @Inject annotation to inject an instance of PollRepository into our controller. The javax.inject.Inject annotation introduced as part of Java EE 6 provides a standard mechanism for declaring dependencies. We use this annotation in favor of Spring’s proprietary @Autowired annotation to be more compliant. In order to use the @Inject annotation, we need to add the dependency shown in Listing 4-15 to the pom.xml file.

<dependency>

        <groupId>javax.inject</groupId>

        <artifactId>javax.inject</artifactId>

        <version>1</version>

</dependency>

Listing 4-15

Inject Dependency in POM File

A GET request on the /polls endpoint provides a collection of all of the polls available in the QuickPolls application. Listing 4-16 shows the necessary code for implementing this functionality. The shortcut annotation declares the URI and the allowed HTTP method. The getAllPolls method used ResponseEntity as its return type, indicating that the return value is the complete HTTP response. ResponseEntity gives you full control over the HTTP response, including the response body and response headers. The method implementation begins with reading all of the polls using the PollRepository. We then create an instance of ResponseEntity and pass in Poll data and the HttpStatus.OK status value. The Poll data becomes part of the response body and OK (code 200) becomes the response status code.

@GetMapping("/polls")

public ResponseEntity<Iterable<Poll>> getAllPolls() {

        Iterable<Poll> allPolls = pollRepository.findAll();

        return new ResponseEntity<>(pollRepository.findAll(), HttpStatus.OK);

}

Listing 4-16

GET Verb Implementation for /polls

Let’s quickly test our implementation by running the QuickPoll application. In a command line, navigate to the quick-poll project directory and run the following command:

mvn spring-boot:run

Launch the Postman app in your Chrome browser and enter the URL http://localhost:8080/polls, as shown in Figure 4-7, and hit Send. Because we don’t have any polls created yet, this command would result in an empty collection.

Note

The downloaded source code contains an exported Postman collection with requests that can be used to run tests in this chapter. Simply import this collection into your Postman application and start using it.

The next stop for us is to implement capability to add new polls to the PollController. We accomplish this by implementing the POST verb functionality, as shown in Listing 4-17. The createPoll method takes a parameter of the type Poll. The @RequestBody annotation tells Spring that the entire request body needs to be converted to an instance of Poll. Spring uses the incoming Content-Type header to identify a proper message converter and delegates the actual conversion to it. Spring Boot comes with message converters that support JSON and XML resource representations. Inside the method, we simply delegate the Poll persistence to PollRepository’s save method. We then create a new ResponseEntity with status CREATED (201) and return it.

@PostMapping("/polls")

public ResponseEntity<?> createPoll(@RequestBody Poll poll) {

        poll = pollRepository.save(poll);

        return new ResponseEntity<>(null, HttpStatus.CREATED);

}

Listing 4-17

Implementation to Create New Poll

Although this implementation fulfills the request, the client has no way of knowing the URI of the newly created Poll. For example, if the client wants to share the newly created Poll to a social networking site, the current implementation will not suffice. A best practice is to convey the URI to the newly created resource using the Location HTTP header. Building the URI would require us to inspect the HttpServletRequest object to obtain information such as Root URI and context. Spring makes the URI generation process easy via its ServletUriComponentsBuilder utility class:

URI newPollUri = ServletUriComponentsBuilder

                        .fromCurrentRequest()

                        .path("/{id}")

                        .buildAndExpand(poll.getId())

                        .toUri();

The fromCurrentRequest method prepares the builder by copying information such as host, schema, port, and so on from the HttpServletRequest. The path method appends the passed-in path parameter to the existing path in the builder. In the case of the createPoll method, this would result in http://localhost:8080/polls/{id}. The buildAndExpand method would build a UriComponents instance and replace any path variables ({id} in our case) with passed-in value. Finally, we invoke the toUri method on the UriComponents class to generate the final URI. The complete implementation of the createPoll method is shown in Listing 4-18.

@PostMapping("/polls")

public ResponseEntity<?> createPoll(@RequestBody Poll poll) {

        poll = pollRepository.save(poll);

        // Set the location header for the newly created resource

        HttpHeaders responseHeaders = new HttpHeaders();

        URI newPollUri = ServletUriComponentsBuilder

                                .fromCurrentRequest()

                                .path("/{id}")

                                .buildAndExpand(poll.getId())

                                .toUri();

        responseHeaders.setLocation(newPollUri);

        return new ResponseEntity<>(null, responseHeaders, HttpStatus.CREATED);

}

Listing 4-18

Complete Implementation of Create Poll

To test our newly added functionality, start the QuickPoll application. If you have the application already running, you need to terminate the process and restart it. Enter the information in Postman as shown in Figure 4-8 and hit Send. Make sure that you have added the Content-Type header with value application/json. The JSON used in the body is shown here:

{

    "question": "Who will win SuperBowl this year?",

    "options": [

                 {"value": "New England Patriots"},

                 {"value": "Seattle Seahawks"},

                 {"value": "Green Bay Packers"},

                 {"value": "Denver Broncos"}]

}

On completion of the request, you will see a Status 201 Created message and headers:

Content-Length ® 0

Date ® Mon, 23 Feb 2015 00:05:11 GMT

Location ® http://localhost:8080/polls/1

Server ® Apache-Coyote/1.1

Now let’s turn our attention to accessing an individual poll. Listing 4-19 gives the necessary code. The value attribute in shortcut annotations (@GetMapping, @PostMapping, etc.) takes a URI template /polls/{pollId}. The placeholder {pollId} along with the @PathVarible annotation allows Spring to examine the request URI path and extract the pollId parameter value. Inside the method, we use the PollRepository’s findById finder method to read the poll and pass it as part of a ResponseEntity.

@GetMapping("/polls/{pollId}")

public ResponseEntity<?> getPoll(@PathVariable Long pollId) {

        Optional<Poll> poll = pollRepository.findById(pollId);

        if(!poll.isPresent()) {

                throw new Exception("Pool not found");

        }

        return new ResponseEntity<>(poll.get(), HttpStatus.OK);

}

Listing 4-19

Retrieving an Individual Poll

In the same fashion, we implement the functionality to update and delete a Poll , as shown in Listing 4-20.

@PutMapping("/polls/{pollId}")

public ResponseEntity<?> updatePoll(@RequestBody Poll poll, @PathVariable Long pollId) {

        // Save the entity

        Poll newPoll = pollRepository.save(poll);

        return new ResponseEntity<>(HttpStatus.OK);

}

@DeleteMapping("/polls/{pollId}")

public ResponseEntity<?> deletePoll(@PathVariable Long pollId) {

        pollRepository.deleteById(pollId);

        return new ResponseEntity<>(HttpStatus.OK);

}

Listing 4-20

Update and Delete a Poll

Once you have this code added to the PollController, restart the QuickPoll application and execute the Postman request as shown in Figure 4-8 to create a new poll. Then input the information in Figure 4-9 to create a new Postman request and update the poll. Notice that the PUT request contains the entire Poll representation along with IDs.

This concludes the implementation of the PostController.

VoteController Implementation

Following the principles used to create PollController, we implement the VoteController class . Listing 4-21 gives the code for the VoteController class along with the functionality to create a vote. The VoteController uses an injected instance of VoteRepository to perform CRUD operations on Vote instances.

@RestController

public class VoteController {

        @Inject

        private VoteRepository voteRepository;

        @PostMapping("/polls/{pollId}/votes")

public ResponseEntity<?> createVote(@PathVariable Long pollId, @RequestBody Vote vote) {

                vote = voteRepository.save(vote);

                // Set the headers for the newly created resource

                HttpHeaders responseHeaders = new HttpHeaders();

responseHeaders.setLocation(ServletUriComponentsBuilder.fromCurrentRequest().path("/{id}").buildAndExpand(vote.getId()).toUri());

                return new ResponseEntity<>(null, responseHeaders, HttpStatus.CREATED);

        }

}

Listing 4-21

VoteController Implementation

To test the voting capabilities, POST a new Vote to the /polls/1/votes endpoint with an option in the request body, as shown in Figure 4-10. On successful request execution, you will see a Location response header with value http://localhost:8080/polls/1/votes/1.

Next, we look at implementing the capability to retrieve all votes for a given poll. The findAll method in the VoteRepository returns all votes in the database. Because this would not meet our needs, we need to add this functionality to the VoteRepository as shown in Listing 4-22.

import org.springframework.data.jpa.repository.Query;

public interface VoteRepository extends CrudRepository<Vote, Long> {

@Query(value="select v.* from Option o, Vote v where o.POLL_ID = ?1 and

v.OPTION_ID = o.OPTION_ID", nativeQuery = true)

        public Iterable<Vote> findByPoll(Long pollId);

}

Listing 4-22

Modified VoteRepository Implementation

The custom finder method findVotesByPoll takes the ID of the Poll as its parameter. The @Query annotation on this method takes a native SQL query along with the nativeQuery flag set to true. At runtime, Spring Data JPA replaces the ?1 placeholder with the passed-in pollId parameter value. Next, we implement the /polls/{pollId}/votes endpoint in the VoteController, as shown in Listing 4-23.

@GetMapping("/polls/{pollId}/votes")

public Iterable<Vote> getAllVotes(@PathVariable Long pollId) {

        return voteRepository. findByPoll(pollId);

}

Listing 4-23

GET All Votes Implementation

ComputeResultController Implementation

The final piece remaining for us is the implementation of the ComputeResult resource. Because we don’t have any domain objects that can directly help generate this resource representation, we implement two data transfer objects or DTOs—OptionCount and VoteResult. The OptionCount DTO contains the ID of the option and a count of votes casted for that option. The VoteResult DTO contains the total votes cast and a collection of OptionCount instances. These two DTOs are created under the com.apress.dto package, and their implementation is given in Listing 4-24.

package com.apress.dto;

public class OptionCount {

        private Long optionId;

        private int count;

        // Getters and Setters omitted for brevity

}

package com.apress.dto;

import java.util.Collection;

public class VoteResult {

        private int totalVotes;

        private Collection<OptionCount> results;

        // Getters and Setters omitted for brevity

}

Listing 4-24

DTOs for ComputeResult Resources

Following the principles used in creating the PollController and VoteController, we create a new ComputeResultController class , as shown in Listing 4-25. We inject an instance of VoteRepository into the controller, which is used to retrieve votes for a given poll. The computeResult method takes pollId as its parameter. The @RequestParam annotation instructs Spring to retrieve the pollId value from an HTTP query parameter. The computed results are sent to the client using a newly created instance of ResponseEntity.

package com.apress.controller;

@RestController

public class ComputeResultController {

        @Inject

        private VoteRepository voteRepository;

        @GetMapping("/computeresult")

        public ResponseEntity<?> computeResult(@RequestParam Long pollId) {

                VoteResult voteResult = new VoteResult();

                Iterable<Vote> allVotes = voteRepository.findByPoll(pollId);

                // Algorithm to count votes

                return new ResponseEntity<VoteResult>(voteResult, HttpStatus.OK);

        }

}

Listing 4-25

ComputeResultController implementation

There are several ways to count votes associated with each option. This code provides one such option:

int totalVotes = 0;

Map<Long, OptionCount> tempMap = new HashMap<Long, OptionCount>();

for(Vote v : allVotes) {

        totalVotes ++;

        // Get the OptionCount corresponding to this Option

        OptionCount optionCount = tempMap.get(v.getOption().getId());

        if(optionCount == null) {

                optionCount = new OptionCount();

                optionCount.setOptionId(v.getOption().getId());

                tempMap.put(v.getOption().getId(), optionCount);

        }

        optionCount.setCount(optionCount.getCount()+1);

}

voteResult.setTotalVotes(totalVotes);

voteResult.setResults(tempMap.values());

This concludes the ComputeResult controller implementation. Start/restart the QuickPoll application. Using the earlier Postman requests, create a poll and cast votes on its options. Then create a new Postman request as shown in Figure 4-11 and submit it to test our /computeresult endpoint.

On successful completion, you will see an output similar to this:

{

    "totalVotes": 7,

    "results": [

        {

            "optionId": 1,

            "count": 4

        },

        {

            "optionId": 2,

            "count": 3

        }

    ]

}