How to migrate your SOAP web service to REST with Camel

SOAP-based services are plentiful in many enterprise solutions and are slowly being replaced by RESTful services to simplify their use. There is a new wizard to help you make the transition with Apache Camel’s Rest DSL added in the latest version of Red Hat Fuse Tooling. This article shows how to use the new wizard to transition from older SOAP-based services to more modern REST-based services.

If you aren't familiar, Red Hat Fuse is an integration platform based on Camel and a number of other projects. The updating Fuse Tooling is available in Red Hat Developer Studio 12.0.0, the desktop IDE that is based on Eclipse 4.8 Photon. You can also get the new wizard by adding JBoss Tools 4.6 to your existing Eclipse 4.8 Photon installation by downloading it directly, or installing via the Eclipse Marketplace.

What is the REST DSL?

The Apache Camel Rest DSL offers an easier way for users to define REST services using common REST verbs such as GET, POST, DELETE, etc. It is available for both the XML (Spring or Blueprint) and Java DSLs as a facade that builds REST endpoints as consumers for Camel routes.

Many examples can be found at the Apache Camel website.

Is the REST DSL supported in the Fuse Tooling Route Editor?

In previous versions of Red Hat Fuse Tooling in Eclipse, there wasn't a good way of rendering this useful functionality. However, with this release, there will be read-only support for the Rest DSL through a new REST tab in the Fuse Tooling Route Editor. (This functionality will be fleshed out in future releases to make it more usable, but for now, you can still edit your Rest DSL in the Source tab and see the details in the REST tab.

Where do my SOAP services come into play?

An older tool called wsdl2rest (now available at https://github.com/jboss-fuse/wsdl2rest) has existed for a while as an unsupported project. This tool simplifies migrating from an existing JAX-WS SOAP-based service to a RESTful service. The tool has been dusted off and improved for Red Hat Fuse 7 and is now a supported part of the distribution, meaning you can use it at the command line using a handful of command-line options and generate a Camel configuration that maps SOAP operations to REST operations. All you have to do is pass the URL to the source WSDL, an output path for generated Java artifacts, an output path for the Blueprint or Spring Camel context file, and details about the JAX-WS and JAX-RS addresses for the endpoints used.

However, we've also enabled an option in the tooling to use this utility. Now you can fire up the new "Camel Rest DSL from WSDL" wizard! The wizard simplifies gathering the required options, boiling it down to selecting the WSDL and a Fuse integration project so it knows what Camel DSL (Spring, Blueprint, Spring Boot) to generate, and you’re off to the races!

How does the "Camel Rest DSL from WSDL" wizard work?

The wizard is available in Eclipse, with Red Hat Developer Studio 12 and the latest version of Red Hat Fuse Tooling installed. To use the wizard, you will need to have a pre-existing Red Hat Fuse integration project in your workspace and access to a WSDL file. You can create a new project by selecting File->New->Fuse Integration Project to open the New Fuse Integration Project wizard and the WSDL file can be local or remote, available via URL.

Once the prerequisites are in place, do the following:

1. Right-click a Fuse integration project in the Fuse Integration perspective and select New->Camel Rest DSL from WSDL or click File->New->Other…, Red Hat Fuse->Camel Rest DSL from WSDL.
2. To choose a WSDL file locally, use the “...” button to the right of the WSDL File field to open a file selection dialog box and choose a file from your file system. If you have a valid URL to a WSDL on the network, you can type the URL in the field directly.
3. If a Fuse integration project is selected in the Project Explorer, it will be automatically selected in the Destination Project field. If not, you can use the “...” button to select the project where you want artifacts to be created.
   
4. Click Next to shift to the Advanced Options page.
5. The Destination Java Folder and Destination Camel Folder fields are pre-populated based on the selected Fuse integration project and the Camel DSL used by the project. There are different default paths based on whether the project is Spring, Blueprint, or Spring Boot. Note that if there are existing files in the directory or the directory has to be created first, warnings will exist to let you know about these conditions.
6. The Target Service Address field corresponds to the SOAP address specified in the WSDL binding, but you can customize it to match the actual address of the SOAP service referenced by the WSDL.
   
7. The optional Target REST Service Address field corresponds to the URL where the REST service will be accessible. This URL is decomposed into settings for the <restConfiguration> and <rest> tags in the Rest DSL to specify the complete URL for REST operations mapped to the SOAP service. If not specified in the wizard, these details can be provided later in the Rest DSL directly.
8. Click Finish.

Once the wizard has completed processing the referenced WSDL file, it generates a new Camel configuration as well as wrapper code in Java mapping the SOAP operations to REST operations. If you open the generated Camel file, you will see the various routes that have been created and the Rest DSL used to map operations. The generated Rest DSL in Camel can be further customized as needed.

Here's the generated Camel configuration in the Design tab of the Route Editor:

This utility provides a jump start for re-using older SOAP-based services in more modern REST-based ways. We look forward to improving on the new REST tab in future releases of the Fuse Tooling!