A RAML / APIHub Plugin for SoapUI

RAML is a relatively new REST API documentation/metadata initiative backed by a workgroup with representation from MuleSoft, Intuit, Box, PayPal, and others. It is similar to initiatives like swagger, api-blueprint, WADL (to name a few) but with some unique twists of its own. RAMLs adoption and eco-system of tools is growing continuously so it seemed like a good (and fun) idea to create a plugin for SoapUI that allows you import RAML files into SoapUI for testing of its defined APIs.

Since the core model of all these REST metadata formats is very similar (resources, actions/methods, query/header/path parameters, representations, etc) - creating the plugin was rather straight-forward given that SoapUI already has pretty solid REST service and testing support. RAML itself uses YAML and comes with a java-parser which can be used to parse RAML files and resolve the described API model - the plugin uses this to resolve and traverse RAML files and create corresponding SoapUI objects.

Since Mulesoft also runs the APIHub API directory - integrating that with SoapUI seemed like a nice idea as well (similar to the ProgrammableWeb Plugin) - and since the APIHub API exposes both RAML and Swagger definitions for its APIs - integrating this plugin with the SoapUI Swagger Plugin makes for an integrated experience, allowing you to:
- Browse the APIHub directory for APIs that have either RAML or swagger definitions
- Import these into SoapUI for functional testing, load-testing, security testing, monitoring, etc.

I won't dwell on RAML itself here - I recommend you have a look at the RAML website and specification. The plugin itself is mainly written in groovy and pretty straightforward, have a look at the GitHub repo for more information on how to build it with maven, etc.

Now, let's dive straight in!

Getting Started

Make sure you have installed either SoapUI 4.5.x or 4.6.2 (or later, 4.6.0 and 4.6.1 had a REST related bug that is now fixed), download the plugin distribution from sourceforge and unzip it into your soapui/bin folder (if you're on a Mac this is under <SoapUI>.app/Contents/Resources/app). If you want to enable swagger support for the ApiHub directory install the swagger-plugin in the same way (download from sourceforge) - the resulting ext and plugins folders should contain the following files:

(the ext folder)

 (the plugins folder)

Now when you start SoapUI you should get the following entries in the soapui log tab at the bottom of the window:










Create a new empty SoapUI project or open an existing one and right-click on the project node; the popup menu should contain the following menu options:

Importing RAML definitions

Selecting the "Import RAML definition" option will open a standard file/URL prompt:

specify a local or remote RAML definition and press OK - it will get imported into SoapUI as a REST Service, allowing you to invoke the API using standard SoapUI REST functionality. For example, below is the service you get when importing the twitter RAML file available at http://www.apihub.com/twitter/api/twitter-rest-api/twitter-rest-api.raml.

Now you're all set to starting testing the imported API - check out the documentation at soapui.org if you need some assistance with getting started.

Importing APIs from APIHub for testing

If you're keen on integrating or testing one of the APIs available in the APIHub directory, the "Add API from ApiHub" menu option is what you need. Selecting it from the project popup opens the following dialog:

The list contains all APIs at APIHub that have RAML definitions - if you have installed the swagger plugin as mentioned above you will see those that have swagger definitions as well (as shown in the screenshot). Select an API and select OK to import it into SoapUI for testing - for example the FitBit API selected in the above screenshot imports as follows:

Shortcomings

One of the major shortcomings in SoapUI is its lack of built in support for OAuth 1/2. Thus, when importing a RAML definition that includes security schemes for OAuth, these will simply be ignored - requiring you to manually add access tokens or credential information to your requests. Another shortcoming is SoapUIs lack of JSON Schema support - any schemas defined in the RAML will currently be ignored.

Next Steps

A natural next step would be to allow exporting of RAML definitions for any REST service defined in SoapUI - which would basically allow you to generate RAML files for existing REST services or those imported from other formats that are currently supported (WADL and Swagger for now). Of course you can also define a REST Service in SoapUI manually by creating resources, methods, adding parameters, etc.

Ultimately though it's up to the users of the plugin to request new features - please don't hesitate to do so at the plugins GitHub page (where you will find more info on building, installing, etc).

Have fun!

/Ole