Virtualizing SOAP services as REST services

Sentinet allows physical SOAP services to be virtualized as REST services. The feature is particularly valuable for existing services, that require non-intrusive exposure of legacy SOAP services as REST APIs. A Sentinet virtual REST service can even be an aggregate service that virtualizes multiple physical SOAP and REST services at the same time. Use the same drag-and-drop procedures to design a virtual REST service by dragging the physical SOAP service version and dropping it on the design surface of a virtual REST service version.

Example of a REST service that virtualizes a SOAP service
Figure. Example of a REST service that virtualizes a SOAP service.

Example of a virtual REST service that aggregates one SOAP service and one REST API
Figure. Example of a virtual REST service that aggregates one SOAP service and one REST API.

Default REST to SOAP mapping

By default, virtualized SOAP operations will be automatically mapped to virtual REST operations, each virtual operations' Uri template taking the form of /[operationName]. The virtual service will expect to receive request messages via HTTP POST, where the request body is the same as the SOAP body, but without the SOAP envelope. The same default rule applies to response messages, the REST client will receive XML response messages stripped out of the SOAP envelope.

REST Request Body SOAP Request Body

Default REST to SOAP messages transformation
Figure. Default REST to SOAP messages transformation.

To modify the default SOAP to REST mapping, modify operation's Request properties in the same way as REST to REST mapping is managed. Click Modify [...] Request button.

Modify operation's Request button
Figure. Modify operation's Request button.

The Request Message Details dialog box shows the default mapping for the REST to SOAP virtual operation. By default, the dialog opens in full screen to accommodate more space for the Request properties, but it can be resized.

Request Message Details dialog box and Restore Size button
Figure. Request Message Details dialog box and Restore Size button.

Notice, that the default Virtual Request properties for the virtual REST operation are:

  1. REST HTTP method is POST.

  2. Virtual REST Uri Template is /[operation name] (which is /Search in this example).

  3. No HTTP Headers mapping is provided.

  4. Virtual Request has only one parameter, Body of a generic Complex type.

  5. Virtual Request Body is marked with Pass-through HTTP request body check-mark in the right side of the screen which shows Virtualized Request properties. That default setting instructs the virtual service operation to expect the request as a plain XML message (as if the SOAP request is stripped out of SOAP envelope and SOAP Body elements).

User can click View Sample Message button to show a sample of the REST Request Body that may be expected by the virtual operation. Sentinet Console shows sample request message here for information purposes only. It helps consumers of the REST service to see what XML message format they have to provide with their request messages.

Sample REST Request message body generated for REST service
Figure. Sample REST Request message body generated for REST service.

Custom REST to SOAP mapping

Most often REST to SOAP transformations require custom transformation of the REST request's URL and/or HTTP headers to the SOAP request body. Sentinet provides capabilities to define custom mapping of the REST operation Uri and its HTTP Headers to SOAP message's parameterized Template.

Variables in a template are placed in curly brackets, such as {myvariablename}. Context Properties can also be part of a template where they are referenced by the Context Properties syntax such as <{mycontextproperty}>.

REST Request Uri Template SOAP Request Template

Example of a virtual REST Uri Template mapping to SOAP body elements
Figure. Example of a virtual REST Uri Template mapping to SOAP body Template.

Sentinet has the knowledge of the underlying SOAP services message schema and helps to generate SOAP request message templates, so that Sentinet users only have to provide variables in these templates (such as {firstName} in the example above) to define custom mapping.

To modify default REST to SOAP mapping, uncheck Pass-through HTTP request body checkbox. With this setting, View Sample Message button changes its title to Generate Template Message and group box title changes to Virtual Request Body Template. The editable text box is populated with the generated message template that can be edited, and where Sentinet users can replace XML elements' or XML attributes' values with parameterized variables.

Replace template elements with parameterized variables (variable name must be placed inside the curly brackets). For example, firstName595 auto-generated constant value in the screenshot above can be replaced with {firstName} variable. From that point, {firstName} variable can be used in the Virtual Uri Template or in the custom Virtual HTTP Headers variables.

Note

Quite often custom REST to SOAP mapping requires changing HTTP method from default POST to GET.

Custom REST to SOAP mapping via HTTP GET method
Figure. Custom REST to SOAP mapping via HTTP GET method.

You can further "refine" REST API Parameters with additional descriptions and requirements. For example, you can mark REST API Parameters as Required, change data Type, etc.

When custom REST to SOAP mapping is used, Request Body Template is sent to a SOAP operation, where parameterized variables are replaced during runtime. That means that any constant values still in the template will be sent "as is". For example, if the template above is defined with <delay> as a constant value, this constant value will always be sent to a SOAP operation, and delay query parameter can be removed from the Virtual Uri Template:

<Search xmlns="http://www.nevatech.com/samples/04/2011/CustomerSearchContract">
  <firstName>{firstName}</firstName>  
  <lastName>{lastName}</lastName>
  <delay>0</delay> 
</Search>

HTTP headers can also participate in custom mappings. For example, figure below shows how HTTP header Delay maps its value to the XML <delay> element of the virtualized request.

HTTP header mapping example
Figure. HTTP header mapping example.

By default, Sentinet generates the SOAP message body template without a SOAP envelope.

If a physical service has custom SOAP headers, then the message template has to be generated with a SOAP envelope, because SOAP headers always exist outside of the SOAP body. Sentinet automatically identifies physical services with SOAP headers and prompts the user to select SOAP 1.1 or SOAP 1.2 format for the message template. It does not matter which format the user prefers. At runtime, Sentinet will automatically use the format that the physical service is configured with. A custom SOAP header may also include template variables that can be mapped to REST API path segment, Query Parameters or HTTP headers.

Advanced REST to SOAP body mapping

Custom mapping described above is typically used when virtual REST service does not have request body (its operations are described with HTTP GET method). If a REST service is expected to have a body (for example in JSON format), which has to be mapped to a SOAP body, then users can use combination of the default mapping described above and the Pipeline components described in Processing Modification Components chapter. For example, a component (or a series of components) placed in the Inbound-Request pipeline can transform incoming JSON message into XML message expected by the default XML body mapping. Components most often used for that purpose are Liquid Transformation, String Replace, Regular Expression and Context Properties.