How to Design RESTful Web Services with Dropwizard
Dropwizard is a Java framework for developing operations-friendly, high-performance, RESTful web services
Dropwizard is a Java framework to develop RESTful web services. It pulls together mature and stable libraries from the Java ecosystem into a lightweight, simple package that let's build production-grade applications. It also provides out-of-box support for configuration, application metrics, logging, and other operational tools.
The most interesting part of Dropwizard is its selection of libraries in order to perform the job. It pulls together best-of-the-class libraries from each domain and let the application developer focus on their task.
Dropwizard uses a plethora of libraries to provide various services in a traditional Dropwizard application. Following are a few critical selections:
Jetty for HTTP
Any web application must have an HTTP server to function as a web application. Dropwizard uses an embedded Jetty container to run the application. Thus, it takes away the complexities of packing the application as an archive and deploy into an application server. This also eliminates a plethora of production issues such as app server configuration, class loader troubles, application logs, memory, and myriad other things. A Dropwizard application has a simple main method that bootstrap the jetty container at application startup and the Dropwizard application is ready to serve. In this regard, Dropwizard behaves exactly in a similar manner of a spring boot application.
Jersey for REST
Nowadays, REST is the default standard for web services. As the primary purpose of a Dropwizard application to develop high-performance web services, it uses the JAX-RS reference implementation as the default implementation to facilitate RESTful web service development.
Jackson for JSON
JSON the default data exchange format in the RESTful web services paradigm and nothing beats Jackson for JSON mappings. Dropwizard uses Jackson as its default mapper for JSON
Dropwizard also uses the following libraries for its internal processing of various aspects of a Dropwizard application. Few notable libraries are listed below:
- Logback and slf4j
- Hibernate Validator
- Apache HTTPClient
Creating a new Dropwizard application
Now that, we have understood what Dropwizard is and few internal libraries, let us create a Dropwizard application to understand these concepts even further. Dropwizard dependencies are exposed as a maven dependency. In this section, we will develop a maven project and add the relevant dependencies.
Step 1: Creating a Maven Project
Open your favorite IDE and create a new maven project with archetype selected as maven-archetype-quickstart. Add the following dependency:
This single dependency ensures that all related components are downloaded and our application is ready to run.
Step 2: Creating a Dropwizard Configuration file
Each Dropwizard application has its own subclass of the
Configuration class which specifies environment-specific parameters. These parameters are specified in a YAML configuration file which is deserialized to an instance of your application’s configuration class and validated. Create the following configuration file.
Above mentioned configuration class extracts firstName and lastName parameters from the supplied YAML file. We will create a YAML file later stage of the application which will have following contents:
Step 3: Creating a Jersey Resource
Jersey resources are the meat-and-potatoes of a Dropwizard application. Each resource class is associated with a URI template. For our application, we need a resource which returns new
Person instances from the URI
/hello so our resource class looks like this:
We are performing the following activities in the above class:
- @Path annotation indicates that this class is a JAX-RS resource
- @Produces indicates that this resource produces JSON data
- @GET indicates that resource can be accessed over HTTP GET
- @Timed let Dropwizard automatically records the duration and rate of invocations as a Metrics Timer
- The method arguments indicate that if data is supplied in the request query parameters, then the same will be used. Otherwise, default values configured in the YAML file will be used
The response returned by the getPerson() method is a Person instance and will be mapped by Jackson. Following is the Person class representation:
Step 4: Creating a HealthCheck
Dropwizard strongly recommends providing health checks for a Dropwizard application. In fact, if health checks are not configured it warns the user at application startup. We have created the following health check for this application:
Step 5: Creating an Application Class
Configuration subclass defined earlier, Dropwizard’s
Application subclass forms the core of a Dropwizard application. The
Application class pulls together the various bundles and commands which provide the basic functionality of the application. Following is the application class:
Step 6: Building the executable jar
We are now done with our Dropwizard application development. We have created the barebones components and added a JAX-RS resource with an endpoint. Let us add the following maven shade plugin in order to build the executable JAR file:
Note the mainClass parameter in the configuration. It must the application main class.
Testing the application
In the previous section, we have developed a Dropwizard application. In this section, we will build and package the application as a Jar file and test the REST endpoint.
Building the application
Execute the following command to build and package the application in a jar file.
Executing the application
Once the jar file is built, execute the jar file with the following arguments:
java -jar dropwizard-demo-1.0-SNAPSHOT.jar server data.yaml
- Change the jar file name according to your configuration
- The first argument supplied to the command is the server, which indicates Dropwizard to start an HTTP server
- The data.yaml is the environment configuration file created earlier. This file must be in the same location of the jar file. Otherwise, provide the absolute path of the file
If everything is fine, then the application starts successfully on default HTTP port 8080 and displays the available endpoints.
Testing the application
In our application, we had exposed one endpoint named /hello.
Accessing http://localhost:8080/hello returns the following content. Note that Dropwizard reads the data supplied in the YAML file and the same is returned as we have not supplied the query parameters.
Accessing the endpoints with firstName and lastName query parameters presents the following output. In this case, the supplied query parameters are used in the response.
In addition, Dropwizard exposes a health check endpoint in the following URL. This provides the resource health. In the following output, we can find our health check configured with the name “default”.
In this article, we talked about Dropwizard and created a demo application to demonstrate the usage of Dropwizard. This lightweight, lean yet powerful framework provides an alternate approach to build RESTful web services with best of the box default configurations.