Multi-language clients with Swagger

Multi-language clients with Swagger

Fabrizio Fortino bio photo By Fabrizio Fortino Comment is a free API that provides current and historical foreign exchange rates published by the European Central Bank (rates are updated every day around 4PM CET).

Although the API is very easy to use, if you want to integrate it in your application you need to write a bit of code. Googling around I have found clients for Python and PHP.

Schema Definition

Since I need to use it in different applications (mainly Java and Go) I have decided to map the API calls and response models in a Swagger Schema using the YAML format.

The definitions section contains the Rates model: an object with 2 properties (base & date) and a dictionary of exchanges where the key (string) is the currency and the value (double) the rate.

paths is where the API endpoints are mapped: the former gets the latest rates, the latter the historical ones.

I have published the schema as a public API on Swagger hub here. The right hand side of the page shows the API in a nicely formatted style. Unfortunately the Try this operation button does not to work due to a javascript bug in the website. As a workaround copy-paste the schema definition in where everything seems to work.

Code Generation

One of the most interesting feature of Swagger is the ability to generate code for the most common languages through the Swagger Codegen project.

The code generation feature is also integrated in Swagger hub. To create a client: click on the download icon on the top-right menu, then Client and finally select a language from the list. In a matter of seconds a zip file with the generated client will be downloaded. It is possible to customize the generated code from the menu Edit Codegen Options.

How to use the clients

Every client implementation is language dependent though they present similarities in term of naming and structure. The following code snippet uses the Java Feign client to access the latest AUD exhange rate for USD.

The Go client provides the functions NewRatesApi and GetLatest to respectively get an handler to the API and invoke the GET request to retrieve the latest rates.

comments powered by Disqus