Getting started with Dropwizard: Connecting to external REST Web-services using Jersey Client

Here is a link to my Getting Started with Dropwizard course on Udemy. Only $10!

Imagine a situation that you would like to create a currency conversion API using Dropwizard, but exchange rates are fickle and change on daily if not hourly basis. So, you need an external source of exchange rate data and luckily, Google search returns a list of such APIs. In this tutorial will connect to Open Exchange Rates which has a free option.

To use the API one needs to obtain a free API key which is an alphanumeric string supplied as part of request string when accessing the API. Here is the description of how to obtain the key. From this moment it is supposed that you have obtained the key, otherwise you will be unable to follow the examples from this tutorial.

Let’s play a little with the API before we start writing the actual code. First, one can obtain the list of supported currencies, this can be accomplished by navigating the following URL

https://openexchangerates.org/api/currencies.json?app_id=<Your API key>

from your browser, where <Your API key> should be replaced with the actual key you obtained earlier. In the first column there are currency symbols that will be used in the api we will build to show the initial currency and the currency of conversion result.

Second, to obtain conversion rates one should navigate the browser to the following URL

https://openexchangerates.org/api/latest.json?app_id=<Your API key>,

where again  the string <Your API key> should be replaced with your key. In addition to rates, there is some supplementary information that we’ll not use in our code. As to the rates data, each row provides the information about how much US Dollar costs in a particular currency. There is also base field in JSON data, which shows relative to which currency the rates are calculated. In the premium version of Open Exchange Rates API one can change the base, but in the free version we’ll have to rely on US Dollar and if we want to convert a sum in Euro to a sum in Canadian dollars, we should calculate the exchange rate based on how much US Dollar costs in Euros and in Canadian Dollars.

Finally, let’s discuss how one can access the API we build. It is supposed, that to obtain the result of conversion one should provide an amount to convert, the currency from which we convert and the one to which we convert. The example code for this tutorial returns the answer if one supplies the browser with a URL like the one below.

localhost:8080/converter/1.5?from=EUR&to=CAD

The API key necessary to call the external API is hidden inside of our code.

Now let’s turn to writing actual code, which can be found in repository here. All explanations of how to create a Dropwizard application and how to expose a REST API are given in this tutorial. In addition, the aforementioned tutorial discusses Jersey client, although there it was used to test the API.

The first step is to add dependency to the pom.xml file of the application.

After that we can add the URL of the external API and its key as well as some client settings to the application YAML configuration file. We discussed earlier how to work with Dropwizard configuration. Here is an excerpt from config.yml file.

The first two parameters are necessary to connect to the Open Exchange Rates API, and you should provide your API key here. In addition, there is group of parameters to configure Jersey client which are not required and were merely added to show how to change the default settings. All parameters have sensible defaults which can be seen in HttpClientConfiguration and JerseyClientConfiguration classes. The full list of settings for the client can be found here. It should be noted, that the HttpClient set and Jersey client set are both applicable to Jersey client.

Then we have to modify the Configuration class and the necessary changes are shown in the snippet below.

Please note that related parameters, such as those to configure the client, are grouped into a class, in JerseyClientConfiguration our case.

After adding client to our application, one can start writing the code to communicate with the Open Exchange Rates API. First of all, we’ll need a representation class that will be used to store the exchange rate date and supplementary information received from the external API. The fields of the class are the same as in the JSON representation above.

We omitted auto-generated getters and setters here.

Now let’s create a resource class which will serve the incoming requests, call the currency API and carry out some calculations. The snippet below shows the code except the method that is used for computations. The latter, along with some ideas of how to test the resource using jUnit and Mockito, can be found in the repository.

All the information about how to create a resource class and process the parameters from the URI provided to the class can be found in this tutorial. In the method, that processes request, we check that the amount to convert was provided, after that we extract conversion rates from the external API and obtain the data for the pair of currencies. The next step is to check if the values for the pair were extracted, in other words, whether the correct currency symbols were provided. And the final step is to calculate the result and returned it to the user.

The last leg of our trip is to register the resource in the run() method of the Application class. The snippet of code is shown below.

We created an instance of client based on configuration and provided API settings to the resource as well.

In this tutorial we learned how to access an external API from a Dopwizard application. Also we learned how to configure Jersey client and got acquainted with a free version of an API that provides currency exchange rates.

Resources

1. HTTP response codes
2. Why not use Double or Float to represent currency?
3. How to Use Java BigDecimal: A Tutorial
4. Dropwizard Client