A Ready! API / SoapUI Pro Retrofit plugin that makes consuming any REST API from Java a breeze

It's been a while - but here comes another SoapUI plugin to make life easier - and since we've released Ready! API the plugin works there just as well (I'm going to refer to Ready! API in the rest of this blog-post - but all applies to SoapUI Pro 5.1+ as well.

Short background; I've been tasked with creating an android app that consumes a public REST API. Using straight-forward HTTP calls seemed a bit old-school so I searched around a bit and found Retrofit - an very nice framework for calling REST APIs via a corresponding Java interface that defines the APIs methods, parameters, etc. The interface has to be created manually - which isn't all that hard if the API is small (which it was in my case) - but it occurred to me that generating the Java interface from some API metadata should be pretty easy - and since I hadn't created a plugin for some time (and I had some hours to spare this weekend) - the opportunity could not be missed.

What exactly is it for?

Say you want to consume a complex REST API from Java - but corresponding Java classes aren't available - and you'd rather not handcode each request using an HTTP client library. If that API has a Swagger definition you're in luck, since Swagger has some nice tools for generating code to consume an API - but more likely there won't be any metadata for this API - or it might be in a format that lacks corresponding tooling to generate client code (RAML, API-Blueprint, etc). Retrofit tries to make things easier in this situation; you define a Java interface that contains methods corresponding to the resources and supported HTTP Verbs in the API - and it automagically generates implementations (and mocks) of that interface that you can use to call the API.

As you are surely aware of by now - Ready! API let's you define and build tests for any REST API - either manually or by importing Swagger, RAML or WADL definitions (using one of the available plugins). Recent versions even has a "REST Discovery" feature that listens in on API traffic and generates REST API definitions, virtualization and tests from it - very cool if you have both the API client and server available.

Since a REST API defined in Ready! API  contains the necessary metadata to generate a Retrofit interface - a corresponding plugin could be helpful - as it would allow you to easily start consuming any API you have defined in SoapUI with the generated code.

Installation

The plugin is distributed using the new Plugin Manager introduced in SoapUI Pro 5.1 - open it from the main toolbar in either SoapUI Pro or Ready! API and select the "Browse Plugin Repository" option - you should get something in the line of:

Select the "Retrofit Plugin" and press the Install button - the plugin will get downloaded and installed - you're all set!

Usage

If you already have a REST API defined in a Ready! API project - just right click the API node and select the "Generate Retrofit Interface" action at the bottom of the popup menu. If you don't I suggest you also install the RAML Plugin (you saw it in the screenshot above also) and use it to browse the APIHub API Directory for an API of your liking (see blog post) - then right click the imported API for the same popup and select the action. I chose to import the GitHub v3 API:

Which resulted in the following REST API being added to my project:

Manually creating a Retrofit java interface for this API is a lot of work - which is where the plugin can really help. Now when I select the "Generate Retrofit Interface" action for this API I get the following dialog:

Select which REST API Resources you want added to the generated interface, specify the corresponding settings - they should be pretty self-explanatory - and press Ok. If all goes well, the plugin will generate the corresponding Retrofit Java interface - for the above settings it generated this GitHubAPI file.

Now you can start calling the GitHub API from Java by following the Retrofit-way of calling APIs - here's a short command-line program to list all repositories using the above generated interface:

The method "getRepositories" being called is part of the generated interface:

(I've bundled this all up in a mini maven project at GitHub for you: github-retrofit-client)

Running this with the argument "smartbear" returns a JSON result containing six repositories - just as expected!

Wrapping up

That's all there is to it - the plugin allows us to easily create Java clients that can be used in both server, desktop and android applications - and for any REST API defined in Ready! API - be it from metadata (Swagger, RAML, API-Blueprint, WADL), from a recording or manually.

The plugin is on GitHub - together with some more technical info - and the possibility to fork, comment, complain, applause - any feedback is as always appreciated

Thanks!

/Ole