Much of my team’s recent development has focused on creating Web APIs to make it easier to share data around the University. For this purpose we are using the Web API framework Dropwizard and a number of other tools including Git, Groovy, Gradle, Codenarc, and Swagger. In this post I will be describing how we have used these tools to implement a reusable Web API development environment.
Information Services uses the Java stack for many applications that benefit from the ease of deployment of “Write once, run anywhere”. We chose Dropwizard largely for compatibility with our existing processes and codebases as there are few other lightweight Web API frameworks in the Java space. We are using the Groovy programming language which compiles to JVM and is compatible with other Java libraries. Groovy is increasingly used in enterprise software development for its compactness and additional features in comparison with Java. While much of our Groovy code is little more than Java with syntactic sugar, Groovy’s functional programming features and emphasis on domain specific languages offer powerful tools for abstraction when they are needed.
One of our uses for Groovy is with Gradle, the dependency management and build automation tool we use. With a suitable Gradle script, it is possible to download dependencies, run automated tests, and compile an application simply by executing the command gradle build. We have been using the Shadow plugin to compile our applications to single JAR files which contain all of the dependencies needed for deployment. Our build pipeline (implemented with Jenkins) continuously builds and deploys these archives with a command line like:
$ java -jar web-api-skeleton-1443208918992-bd8adef-all.jar server configuration.yaml
Another Gradle plugin we use is Codenarc, a static code analysis tool for Groovy. Run at the same time as our unit tests, our Codenarc rules alert developers to violations of our style guidelines. Although it is just a convenience, it has saved our team some time spent discussing style issues during code review.
An important aspect of developing Web APIs is documenting HTTP resources, methods, and messages. Although there are no formal standards, Swagger is increasingly used to specify and define Web APIs in a machine- and human-readable format. We use Swagger to communicate the structure and function of our services by integrating with our Web API gateway and by generating a point-and-click interface for exploration.
Dropwizard describes itself as “a Java framework for developing ops-friendly, high-performance, RESTful web services” that “pulls together stable, mature libraries from the Java ecosystem into a simple, light-weight package that lets you focus on getting things done.” It was initially released in 2011 and at the time of this writing is at version 0.8.2. Dropwizard favors certain conventions but leaves most design decisions up to the application developer. Its bundle of libraries for HTTP, JSON, logging, testing, monitoring, and databases is the source of both its power and its complexity: Although a great deal of functionality is available out of the box, some effort is required to understand the way the libraries interact.
The structure we have been using for our Dropwizard projects generally consists of classes defining the application and its configuration, custom data types, resources mapping URLs to method calls, database access objects, authentication, and automated tests. We have developed a Web API Skeleton that can be cloned easily with Git to reuse code and distribute updates between multiple applications. We have developed a number of Web APIs to test various features of Dropwizard, integrate with other University systems, and train new employees. These include our Dropwizard Test, Student Application Decision, REST Performance Ranking, Catalog API, and Locations repositories which are all freely licensed and available on GitHub.
For more information and a detailed demonstration of Dropwizard and our other development tools, watch the following 30-minute screencast:
