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

Getting Started with the new SoapUI Plugin system

SoapUI 5.1 introduces a totally revamped plugin-architecture that makes it substantially easier to extend SoapUI with custom actions, teststeps, assertions, etc. The main parts of this are:

• An improved PluginLoader that loads plugins into their own ClassLoader - allowing plugins to have 3rd party dependencies that don't collide with other plugins or SoapUI itself
• An annotation-based extension mechanism for creating plugin classes (no more XML...)
• An integrated PluginManager that allows you to install/uninstall/upgrade plugins via the UI
• A plugin-repository hosted by SmartBear to which you can submit your own plugins so anyone can download them via the PluginManager
• A maven archetype for easily creating new plugin projects using either java or groovy as the development language

Let's create a simple plugin to illustrate some of these steps.

Prerequisites

As you hopefully know - SoapUI is a desktop tool for all aspects of API Testing that you'll need to download and install from smartbear.com. Creating plugins is simplified by having a java/groovy development environment, for example Intellij or eclipse. You'll also need maven for the actual building of the plugins. I won't dive any more into this since I expect you to have all this sorted out already :-)

Creating a simple search plugin

The maven archetype will generate the basic plugin project for you; open a command-prompt in a folder where you want to create the plugin project and type the following:

mvn archetype:generate -DarchetypeGroupId=com.smartbear.maven.archetypes -DarchetypeArtifactId=soapui-plugin-archetype -Dmaven.repo.remote=http://www.eviware.com/repository/maven2

This will download and install the maven archetype and start generation of the plugin project. You will be prompted for a number of properties - set these as follows:

• groupId: "com.mycompany"
• artifactId : "my-soapui-plugin"
• version : "1.0.0"
• package : <empty>
• language : "java"
• type : "Action"

maven will do some work and generate the default project for you - you should see something in the line of the following in your command-prompt:

Now go into the created "my-soapui-plugin" directory and run "mvn install" from the command-line - this will build the plugin and package it for installation - you will get something like the following:

Let's install this plugin in SoapUI 5.1 - start SoapUI and open the PluginManager from the main toolbar:

Select the "Load plugin from file..." button at the bottom of the PluginManager dialog and navigate to the generated plugin in the target folder of the plugin project:

Press "Open" and the plugin should get installed:

Close the Plugin Manager and right-click on any open project in your SoapUI workspace (this is where the default plugin action is installed) - you'll see the plugin action at the bottom of the menu:

Presto - that was easy! Your first SoapUI Plugin is installed and running - and you didn't write one line of code!

Customizing the plugin to do a search in our project

Although it works - the plugin currently doesn't do much (it just shows a hello message). Let's improve the plugin to actually do something useful - search and open a list of matching items in the selected project.

Open the project in your java development environment (i'll leave the details of that to you...) and navigate to the PluginAction.java file that was generated via the maven archetype:

You can see the default implementation of the perform method - it just shows a "Hello from..." message in a popup window.

Now comes the hard part - knowing your way around the SoapUI object model and APIs - have a look at The SoapUI Object Model to get an introduction and pointers to relevant javadocs.

What we'll do is change the perform method to first prompt for a search string, then do a recursive search through all items in the select project to find those with a matching name (using the specified search string as a regular-expression) - and finally display the results in a ModelItemListDesktopPanel:

As you can see, I've also brushed up some of the metadata in the constructor - and the generated PluginConfig.java file has been updated accordingly:

together with updated metadata in the pom;

    <name>SoapUI Search Plugin</name>

    <artifactId>soapui-search-plugin</artifactId>

    <groupId>com.smartbear.soapui.plugins</groupId>

Now when we build and install the plugin (uninstall the previous version first in the Plugin Manager) - we get the following item in the popup menu:

which prompts as follows when selected:

and uses the specified regular-expression to find items in the selected project and display them:

Double-clicking an item in this window opens the corresponding desktop panel for editing. Marvellous!

Next Steps

That's all there was to it - the plugin is ready to by submitted to the plugin repository and spread to thousands of SoapUI users out there.

The above plugin is available on GitHub - feel free to fork and improve it, ask questions or just use it. 

And as always - I'm looking forward to hearing from you.

/Ole

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

Updated Swagger support for SoapUI

I've finally found some time to update the SoapUI Swagger plug-in to be compliant with both the new swagger version 1.2 and the really old 1.0. You should now be able to import any 1.0, 1.1 and 1.2 compliant swagger into SoapUI - if you can't please let me know so I can make more improvements.

From a functionality point-of-view there is no change to the previous version - download the plugin and unzip it into the soapui/bin folder; the zip will add files to the ext and plugins folders (be sure to remove any previous versions from these folders). For more details on how to use and install the plugin please check out the initial blog-post.

The plugin source code is as previously available at GitHub under the apache license.

Under the Hood - swagger4j 1.0 beta2

Driving most of these changes is an update to the swagger4j library used by the plugin - swagger4j is a standalone java library that basically provides a Java object model and corresponding readers and writers (much like other XXX4j libraries) for swagger resource listings and API declarations. Currently it doesn't support for the model-element of swagger, although that is something that I hope to support whenever a java library for JSON Schema is made available.

swagger4j is at GitHub as well - open source for your pleasure.

Outstanding Shortcomings

The major shortcomings in the plugin are related to corresponding lack of functionality in SoapUI; OAuth support (which I know the SoapUI team is working hard on for the next major release) and JSON Schema support. Thus, if your swagger contains authorizations metadata this will be "lost" when importing your Swagger into SoapUI (although the underlying swagger4j library makes it available) and you will have to set up any access-token/apiKey/authorization headers manually. Also, any JSON schemas/models in your swagger will be ignored during the import as SoapUI currently works exclusively with XML Schema for payload metadata.

As soon as support for these features is available in SoapUI, I will strive to update the plugin accordingly.

What's next?

The next major undertaking under consideration is integrating the swagger codegen utilities into the plugin which would allow you to generate code for any API defined in SoapUI (be it from Swagger, WADL or manually) for the 10+ languages supported by the swagger toolkit. Please let me know if that sounds intriguing (or if it doesn't) and of course don't hesitate to suggest any other functionality you might want to see in this plugin.

Thank you!

A SoapUI Plugin for Runscope

Another week - another cool API-related service! This time it's Runscope - a web application that basically allows you to record and replay API requests and responses that get routed through their platform - with a bunch of additional bells and whistles.  It was launched publicly at GlueCon a couple of weeks ago - and although I'm not quite sure of the use case I couldn't resist creating a very simple SoapUI plugin that easily lets you run your requests through their platform instead of directly to the target endpoint.

To run your requests through Runscope you simply need to modify the endpoint as described at https://www.runscope.com/docs - obviously an easy task for a SoapUI RequestFilter - let's get busy!

The Plugin Code

The plugin code is extremely simple; the main artifact is a SoapUI RequestFilter that modifies the request endpoint as described in the Runscope documentation. Since a bucket-id is required, the plugin looks for a Project-level property named "RunscopeBucket" - if it exists its value will be used accordingly.

The filter is written in groovy:

(see the latest version at GitHub)

The only other thing needed in the plugin is a listeners.xml file that adds this listener to the SoapUI RequestFilter Registry:

The project as a whole looks as follows in IntelliJ

and can be found on GitHub at https://github.com/olensmar/soapui-runscope-plugin.

In action

Download the plugin from sourceforge and save it into the SoapUI/bin/plugins folder - when SoapUI starts you will see the following in the SoapUI log:

Now add a "RunscopeBucket" property to your SoapUI project and set it to a valid Runscope Bucket identifier:

All requests in your project will now be sent through Runscope - and recorded by it for inspection, replay, etc. You can see the modified endpoint in the Raw tab of the request:

(and of course you can see the captured requests in the Runscope console)

Be cautious though; when I say all requests, I mean all requests - included those in a LoadTest, SecurityTest, etc. If you forget to unset the "RunscopeBucket" property you can easily fill up your bucket at Runscope in no time.

Runscope has the option of not forwarding your request to its target endpoint - so you can "debug" and record the outgoing request without loading the target service - to enable that add a property named "RunscopeCapture" to your project and set it to "true" - this will modify the outgoing endpoint accordingly.

Wrapping up!

That's it - nice and easy. Download the plugin from sourceforge and have a go - let me know if you have any issues or want any improvements!

Thanks,

/Ole

SoapUI + Swagger = true!

Since I published the original version of the soapui-swagger-plugin in late 2012, Swagger has continued to gain traction within the API community. For those of you not familiar with Swagger, it's a metadata format for describing the ins and outs of a REST API - much like WSDL is for SOAP APIs - have a look at the Swagger website to learn more.

The initial version of the plugin allowed you to import Swagger definitions into SoapUI - making it extremely easy to send ad-hoc requests, create functional tests, load tests and API monitors for the Swagger-described API (and all for free!). When discussing the plugin with some users at APIStrat earlier this year, they requested the possibility to be able to export Swagger definitions as well, i.e. if you have a REST API defined in SoapUI - they wanted to be able to generate a corresponding Swagger definition that they (for example) could use with swagger-ui to provide your customers an online tool for trying out your API.

Obviously I couldn't resist the challenge, and although its taken me some time I'm happy to finally announce version 0.2 of the plugin that does exactly that; exports Swagger definitions for any REST API defined in SoapUI - which has some cool usage scenarios. Let's dive in.

REST APIs in SoapUI

Despite its contextually unfortunate name - SoapUI has had good support for testing REST APIs since 2008 (!). REST support was initially modeled around the WADL specification (an initial attempt at providing metadata for REST APIs) - fortunately the object model in Swagger plays pretty well with WADL, which makes the Swagger import/export feature in the plugin play seamlessly with SoapUIs REST support.

Exporting Swagger Definitions

Exporting Swagger definitions using the plugin is straightforward; make sure you have at least one REST API defined in your SoapUI project and right-click the project node in the SoapUI navigator; the popup menu now has an "Export Swagger" menu option:

Select it to bring up the following dialog:

The settings are as follows:

• APIs : select which REST APIs in your project that you want to include in the generated Swagger definition
• Target Folder : where to generate the files
• API Version : the value for the api-version property in the generated definitions
• Base Path: the base path that the generated resource listing will be hosted on. This is important to get right as API declarations are resolved relative to this (see example below)
• Format : which format to use; Swagger technically supports both json and xml, although I would guess 99% of its users are using json at this time :-)

Press the OK button when you've set the options as desired; SoapUI will work a little and prompt you with the path of the generated Swagger resource listing. This is ready to go; feed it into any other tool that supports Swagger - for example you can use swagger-ui to provide a nice online UI for exploring the described API (see example below).

Usage Scenarios

Although the primary usage scenario may be the one described further down in this post - generating Swagger definitions for hosting them with swagger-ui - you could of course use the export feature of the plugin for things like:

• WADL to Swagger conversion; if you have API definitions in WADL format you can simply import them into SoapUI (using the regular Add WADL functionality) and then export them as Swagger definitions with this Plugin
• Swagger-creation; if you need a visual tool to build Swagger definitions "from scratch" you can use SoapUI to define your REST API which you can then export.

Hosting Swagger definitions with SoapUI

One thing you might want to do is provide your API users with a nice browser-based UI for trying out your API - which is precisely what the swagger-ui project is for (also from the Swagger folks). You can download swagger-ui from GitHub and just open it from your local file system in your browser - which will start you with something like:

(by default it displays the sample petstore Swagger definition)

Now how do you get swagger-ui to read the resource-listing generated by SoapUI? Unfortunately swagger-ui doesn't support file-based URLs so we need to do a bit of trickery with SoapUI to expose our Swagger for swagger-ui; the MockService functionality in SoapUI can be used as a miniature web-server, which is just what we need here (if you have a local web server running you can of course use that instead).

Start by creating a MockService in your SoapUI project via the Project menus "New MockService" option. Once created - double-click it to open the MockService window and select the "Options" button - which will bring up the following dialog:

Set the docroot to point at the folder where you generated the Swagger definition, configure the port as desired (so it doesn't collide with anything else you might be hosting on your machine), press OK and start the MockService with the "Run" button in the top-left corner of the MockService window. You now have a mini webserver running, ready to serve any documents you have in the specified docroot folder, but before we can use swagger-ui with it we need to make sure the MockService adds some HTTP Headers that swagger-ui expects. Select the "OnRequest Script" tab in the MockService window and enter the following:

mockRequest.httpResponse.addHeader( "Access-Control-Allow-Origin", "*" )
mockRequest.httpResponse.addHeader( "Access-Control-Allow-Methods", "GET, POST, DELETE, PUT" )
mockRequest.httpResponse.addHeader( "Access-Control-Allow-Headers", "Content-Type, api_key, Authorization" )

In SoapUI, this looks as follows;

Let's go back to the dialog for Exporting Swagger definitions and configure it accordingly:

Please note that Base Path configuration above matches the local ip that the MockService is running on (so the path can be resolved) and the Target Folder is the same as the docroot for the MockService configured above. Once exported we're all set; open a web-browser and enter "http://127.0.0.1:8181/api-docs.json" (change the port accordingly) - which should bring up the Swagger resource listing we generated above;

Now back to swagger-ui; paste the same endpoint in the URL field and press the "Explore"; swagger-ui will work a bit and presto, you should get something like the following;

Awesome - we've created Swagger definitions for some of the Google Maps APIs and can now do some simple API invocation from within swagger-ui!

Changes to the Import Swagger feature

The "Import Swagger" feature has been improved a little since last; the dialog invoked by the corresponding menu item now looks as follows:

Here you can now specify to import Swagger API Declarations directly (instead of always having to provide a Resource Listing) - which can come in handy for some of the API-mgmt platforms out there that provide API Declarations directly (APIHub for example).

A bonus under the hood: swagger4j

Version 0.2 of this plugin needed a more robust way to read and write Swagger definitions than the groovy scripts that were used in version 0.1 to just read them. I've separated this into a separate java library - swagger4j - which has no dependencies on SoapUI whatsoever and can as such used within any Java program that needs to read or write Swagger definitions. It's open-source (Apache licensed) and available over at GitHub - check it out, and don't hesitate to give me feedback so I can improve that as well.

Installation

Installing the plugin is straight forward; download it from sourceforge or build it yourself with maven (it's on GitHub). The download from sourceforge contains the required dependencies - all you have to do is unzip it into your SoapUI/bin folder.If you build it manually you will have to add these dependencies yourself to the SoapUI/bin/ext folder:

• swagger4j - available at sourceforge
• javax.json-api - available at java.net

Next Steps

So what's next? You tell me! Please get in touch if you want to see any specific fixes, improvements, etc - I'd love to hear from you.

Thanks,

/Ole

Another #APIStrat Conference Recap

I had the great pleasure of attending the APIStrategy Conference in NY together with @lindybrandon and @davidyaches from SmartBear a little more than a week ago - it was a great event with a good mix of topics, people, discussions and hangouts. I've tried to sum up some of the stuff that has stuck with me over the following days – hopefully you will find some interesting tidbits in there.

Lots of Passion 

This is my major take-away from the conference; the API community is having a blast! Geeks, hipster coders, architects, business developers, senior marketers, sales and product owners - they were all there gathered for the feast - and they were feasting together. Historically I have often seen a divide; geeks are passionate, business is skeptical- or business is raving and the geeks don't get it. Here though they are all rowing in the same direction - helping and complementing each other - it was awesome to behold, and holds great promise for future developments in this movement.

Of course - there was quite a lot of competition as well. For example the panel discussions on API Management and PaaS sometimes had a "mine is bigger than yours" component that was quite enjoyable for the audience - but surely challenging for the participants. The players are both startups and existing enterprises that have adapted their offerings to the API space, both have their pros and cons; who will win in the end is definitely still out in the open.

Swagger FTW

Swagger is a metadata format for describing REST APIs, and as such it can be used to generate code, documentation, tests, mocks, etc. It's an open-source project created by the wordnik folks, now hosted by a spinoff named Reverb. When I first encountered it a couple of months ago I was a bit surprised given the existence of WADL which is an older standard that solves all the same problems. Given the situation at hand, Swagger has definitely succeeded where WADL has failed; it has been adopted by many of the API management and tool vendors at the conference, and it’s looking to be the primary choice for many REST projects out there (based on my experience talking to SoapUI users both at the conference and besides).

There are probably many reasons for its initial success (apart from a cool name); it is based on actual API usage, has a tooling ecosystem, prefers JSON and the Swagger-UI just looks great. WADL on the other hand is "just a spec", sounds suspiciously like WSDL and lacks the "underground appeal" of the Swagger community. Hats off to the Reverb team – hopefully they can govern and evolve Swagger in line with trends in the API community.

Academically, I find it interesting that a metadata format catches on at all in the REST community; much of the initial driver behind REST was to move away from metadata and specifications, and while the more biblical REST crowd talks about hypermedia APIs as a means to avoid metadata and tight coupling between client and API - the pragmatic users seems to realize the benefits of metadata in an enterprise setting (more on that below). In the end, I think whatever the API community finds best solves their problems to "get the job done" will prevail.

The religion of REST - and beyond

REST has been around for a while now - the original dissertation by Roy Fielding was published in 2001 - but it didn't really catch on until developers got fed up with the proliferation of WS standards and needed a much simpler way to consume data in the client AJAX applications around 2007-2008. Recent developments within the core REST community have me worried though; talking about "REST maturity levels" and "real REST" while quoting Mr. Fielding’s dissertation as their holy parchment gives at least me a bitter aftertaste; many of the current REST adoptions and APIs are perfectly fine and provide excellent value to their users even if they don't follow HATEOAS principles or use something like HAL to expose hyperlinks. If you're providing APIs I suggest you approach these with a grain of salt, the main goal of your API is to swoon its users, not follow design principles (although these could of course complement each other).

Back to the conference; while there was a lot of talk about the promise and implementation of hypermedia APIs and HATEOAS principles, the Netflix story told by Daniel Jacobson took things to the next level; REST wasn't a good fit for them as it put too much overhead on their client applications (tailored to 800 different clients!) which assembled their pages from a multitude of REST APIs. Their solution was to create an "orchestration layer" on the backend that assembled data from the internal APIs into what they called an "experience API". This was consumed by the device and exposed data selected specifically for that user – and as this API didn't follow any REST principles it doesn't qualify as such - it's just an API that works.

Incidentally - if you are old enough to remember (like I am) - this is similar to the move from RPC style web services to document style that happened around 10 years ago; instead of making multiple smaller calls to assemble a final result, the actual orchestration logic of all those pieces was meant to be done in one go on the server and returned in one document.

The Enterprise strikes back

So this is an interesting (but not totally unexpected) development; first, the coder community got tired of enterprise madness and SOAP and adopted REST as a means to actually deliver something of value within a reasonable time-frame. The enterprise SOA shops chugged along with their SOAP-based SOA projects, but eventually they started to realize that APIs are actually good for them too. This was not just from a technical point of view, but even more as a business enabler - allowing to bring their products to a whole new group of consumers (via APIs). Unfortunately though, the REST-based API community lacks solutions for some key requirements for many enterprises;

• Security; transport-level security provided by SSL is far from enough for health care, banking, etc - how does REST support persistent signatures and encryption!?
• Governance and Policies; how can enterprise APIs be governed through their entire lifecycle? Laura Merling from AT&T gave a great talk on how they are creating APIs with governance in place, and Lorinda Brandon wrote a great piece on the subject, check it out: Governance vs Innovation
• Transactions and Reliable Messaging; is HTTP good enough for messaging requirements that are beyond request/response? What alternatives are there?

Many of the talks at the conference highlighted the need for solutions to these problems - and I'm sure they can be solved, I'm just hoping that we in 3 years’ time won't have the same WS-(death star) mess that the SOAP community got into when the major vendors initially tried to solve these problems on their own, and then got together in extremely sluggish committees to try to unite the standard into a common one.

SoapUI does REST damnit!!

I guess this is a little off-topic but I'll take the opportunity; several people I talked to at the conference regarding testing of their APIs with SoapUI squarely countered with "we don't do SOAP". <rant>This is so frustrating! SoapUI has had extensive REST support since version 2.5 released in 2008; resources, HTTP Verbs, representations, parameters, URL-templates, JSON, XML, content-negotiation, security, you name it. You could easily set it up to test true hypermedia APIs and now there is even a swagger plugin that allows you to import swagger definitions, and given all its other testing features (and that it's actually free) it should definitely be part of an API testing strategy </rant>.

Thank you!

I’ll end with a huge thanks to all at the conference for their presence and passion, and an extended thanks to Kin Lane for his insightful and extremely knowledgeable apievangelist.com blog and his commitment to the API movement. Hope to see you all at the next conference – please share your thoughts on the above and the conference in whatever medium you find appropriate.

/Ole
@olensmar