SOA Suite 12c: Introducing the REST Adapter

The REST Adapter is an important new feature of Oracle SOA Suite 12c. This new adapter allows easy calling/exposing of RESTful services (see http://javaoraclesoa.blogspot.nl/2014/05/what-is-rest.html for an introduction to REST) based on a WADL or configured manually. Not only does Oracle introduce the REST Adapter, but JSON support is also added in SOA Suite 12c. These features will greatly increase the integration options and flexibility of Oracle SOA Suite. In this blog I'll describe how a RESTful service can be called by using the REST adapter. Exposing a RESTful service will be described in a later blog.

Calling RESTful services in Oracle SOA Suite

SOA Suite 11g

In recent history (SOA Suite 11g) there were no out of the box options to integrate with or expose RESTful services. Also there were no out of the box options to handle JSON payloads. Since Oracle SOA Suite has many options for integration with Java code, there are several workarounds such as using the SocketAdapter (http://javaoraclesoa.blogspot.nl/2012/12/receiving-json-requests-in-oracle-bpel.html) or using the Spring component (http://technology.amis.nl/2009/12/16/soa-suite-11g-using-spring-component-to-mimic-http-binding-and-integrate-restful-services/). These workarounds however all have major drawbacks and it is difficult to set them up in such a way that they are flexible and the code is maintainable.

SOA Suite 12c

SOA Suite 12c introduces the REST adapter to make life a lot easier.

A picture of the technology adapters in Oracle SOA Suite 12c

The REST Adapter can be configured in 2 ways. Manually or by means of a WADL (Web Application Definition Language). The manual definition will not be described in detail since the result should be the same as is done by means of a WADL. This also nicely illustrates that using a WADL is preferable.

Using a WADL

A WADL for REST services can be compared to a WSDL for SOAP services. As with SOAP services, using a predefined definition file makes the configuration easier. This is especially true when calling REST services. Some frameworks provide out of the box WADL's such as JAX-RS (see for a simple implementation example; http://javaoraclesoa.blogspot.nl/2014/05/what-is-rest.html). If a WADL is available, use it. It is more likely more complete then what you can create yourself. When there is no WADL available, a third party tool can be used to generate a WADL. Smartbear SOAP UI for example. In SOAP UI you can configure a RESTful service and SOAP UI will generate the corresponding WADL for you for free. 'naam' in the below screenshots is dutch for 'name'.

Create a new REST project in SOAP UI

Create a REST service from an URI

After inputting an URI, a request is generated in SOAP UI

SOAP UI generates a WADL for you based on the defined REST service

A WADL is generated.

The generated WADL can be viewed and used to configure the REST adapter. Now back to the SOA Suite. Configure the REST binding based on a WADL.

The WADL chooser supports URL's to download a WADL from. Also deployed SOA composites or OSB proxies can be selected which provide a RESTful interface. A deployed JAX-RS service however cannot be selected.

The WADL chooser

There were some warnings after parsing the WADL. Nothing fatal. Mostly request/response message definitions missing.

The configuration for the binding is generated after reading the WADL

For the operation bindings, Template and Query style REST parameters are supported (see http://www.soapui.org/REST-Testing/understanding-rest-parameters.html for an overview of REST parameter types). When you edit an operation binding, you can specify the response message. The request is defined by the resource definition. The response can be JSON or XML. You can also specify the expected response HTTP code.

An example of a configured JSON response.

When you have configured the REST Adapter, it is easy to do the assignments as usual in BPEL (or Mediator or BPM, whatever you like). Now you can call a REST service returning a JSON message and convert the reply to XML to do the things you usually do with the SOA Suite.

An example BPEL process in which a REST service is called synchronously.

Also the Enterprise Manager supports parsing WADL files to easily test services.

A WADL can be parsed from the Enterprise Manager test console.

JSON support with the Native Format Builder

In the above sample I've used a service which obtained it's parameters from a GET request and returned a JSON payload. The JSON payload is converted to XML and can be processed as usual. JSON support is new in SOA Suite 12c. Also several other native formats are supported such as MFL. Message Format Language (MFL) was previously used by the OSB 11g as an alternative to the NXSD used in the rest of the SOA Suite (mainly the file adapter).

JSON message format is supported and also Message Format Language (part of the OSB in 11g)

Generating an NXSD to describe a sample JSON file

My first try at importing a WADL failed because I had neglected to use certain annotations in my JAX-RS RESTful service (see http://javaoraclesoa.blogspot.nl/2014/05/what-is-rest.html for correct sample code). The response could not be determined in this case (and the wizard would not let me set it manually). I manually created an NXSD file and referred to it in the WSDL generated for the REST binding. This implementation method of JSON support with NXSD and the usage of NXSD by the REST adapter leaves the door open to more options for interaction with the SOA Suite. More on this in a later blog post.

This blog post describes calling a RESTful service with the REST adapter. I have also written an article on exposing a composite with a RESTful interface.