Skip to content

Convert a JSON Message to SOAP and SOAP to JSON


This tutorial uses the WSO2 API Manager Tooling Plug-in and the PhoneVerification API created in Create and Publish an API.

The API Gateway has a default mediation flow for the API invocation requests that it receives. You can extend this default mediation flow to do additional custom mediation for the messages in the API Gateway. An extension is provided as a synapse mediation sequence. You can design sequences using a tool such as the WSO2 API Manager Tooling Plug-in and then store the sequence in the Gateway's registry.

Let's see how to convert message types using custom sequences. In this tutorial, we convert a JSON payload to SOAP before sending it to a SOAP backend. Then we receive the response in SOAP and convert it back to JSON.

  1. Log in to the API Publisher and click the PhoneVerification API.

  2. Create the following resource and add it to the API.

    !!! tip

    Tip : The resource you create here invokes the SOAP 1.2 Web service of the backend. Therefore, the recommended method is HTTP POST. As you do not include the payload in a query string, avoid giving any specific name in the URL pattern, which will be amended to the actual backend URL.

    Sample value
    Resources URL pattern /*

    Request types


  3. After the resource is added, expand it and edit the parameter as follows. This parameter is used to pass the payload to the backend.

    Summary & Description Parameter Type Content-Type
    Pass the phone number and license key body application/json

    Next, let's write a sequence to convert the JSON payload to a SOAP request. We do this because the backend accepts SOAP requests.

  4. Navigate to the Endpoints section and change the endpoint of the API to

  5. Click Save to save the Endpoint details of the API.

  6. Download and install the WSO2 API Manager Tooling Plug-in if you have not done so already. Open Eclipse by double clicking the file inside the downloaded folder.

  7. Click Window > Open Perspective > Other to open the Eclipse perspective selection window. Alternatively, click the Open Perspective icon shown below at the top right corner.

  8. On the dialog box that appears, select WSO2 API Manager and click OK.
  9. On the API-M perspective, click the Login icon as shown below.

  10. On the dialog box that appears, enter the URL, username, and password of the Publisher server.

  11. On the tree view that appears, expand the folder structure of the existing API.

  12. Right-click on the In sequence folder and click Create to create a new In sequence .

  13. Name the sequence JSONtoSOAP.
  14. Your sequence now appears on the APIM perspective. From under the Mediators section, drag and drop a PayloadFactory mediator to your sequence and give the following values to the mediator.

    !!! tip

    Tip : The PayloadFactory mediator transforms the content of your message. The <args> elements define arguments that retrieve values at runtime by evaluating the provided expression against the SOAP body. You can configure the format of the request/response and map it to the arguments.

    For example, in the following configuration, the values for the format parameters PhoneNumber and LicenseKey will be assigned with values that are taken from the <args> elements (arguments,) in that particular order.

    For details on how you got this configuration, see PayloadFactory Mediator in the WSO2 EI documentation.

|         |                                                                                                                                                                             |
| Payload | ``` xml                                                                                                                                                                     
      &lt;soap12:Envelope xmlns:xsi="" xmlns:xsd="" xmlns:soap12=""&gt;  
              &lt;CheckPhoneNumber xmlns=""&gt;                                                                                                     
| Args    | Give the arguments as a json expression as follows:                                                                                                                         
  &lt;col width="33%" /&gt;                                                                                                                                                          
  &lt;col width="33%" /&gt;                                                                                                                                                          
  &lt;col width="33%" /&gt;                                                                                                                                                          
  &lt;tr class="header"&gt;                                                                                                                                                          
  &lt;tr class="odd"&gt;                                                                                                                                                             
  &lt;td&gt;&lt;div class="line number14 index13 alt1"&gt;                                                                                                                                 
  &lt;code class="java string"&gt;                     //request/PhoneNumber                    &lt;/code&gt;                                                                              
  &lt;tr class="even"&gt;                                                                                                                                                            
  &lt;td&gt;&lt;code class="java string"&gt;                    //request/LicenseKey                   &lt;/code&gt;&lt;/td&gt;                                                                        
  &lt;/table&gt;                                                                                                                                                                     |
  1. Similarly, add a Property mediator to the same sequence and give the following values to the property mediator. This mediator changes the payload type of the outgoing message to soap+xml. More information about the Property mediator can be found here.

    Property Name messageType
    Value Type Literal
    Value application/soap+xml
    Property Scope axis2
  2. Save the sequence, which is in XML format (e.g., JSONtoSOAP.xml ). This will be the In sequence for your API. Next, create an Out sequence.

  3. Right-click on the Out sequence folder and click Create to create a new Out sequence .

  4. Name the sequence SOAPtoJSON .

  5. Add a Log mediator to the sequence and give the following values. Note that the property value provided is a string literal.

    !!! info

    The Log mediator is used to log mediated messages. Having a custom log level allows logging only the properties added to the Log mediator configuration. More information can be found here .

    Log Category INFO
    Log Level CUSTOM
    Log Separator ,
    Properties Name: TRACE
    Type: LITERAL
    Value/Expression: Global Mediation Extension

  6. Similarly, add a PayLoadFactory mediator with the following values. This mediator in the out sequence is used to transform the SOAP message content returned from the backend into JSON.

    Payload Format Inline
    Payload <CheckPhoneNumber xmlns=" "><PhoneNumber>1</PhoneNumber><LicenseKey>2</LicenseKey></CheckPhoneNumber>
    Args Type: Expression
    Value: //request/PhoneNumber
    Evaluator: xml

    Type: Expression
    Value: //request/LicenseKey
    Evaluator: xml
    Media Type xml

  7. Finally, add a Property mediator with the following values. This mediator changes the payload type of the incoming message to JSON.

    Property Name messageType
    Property Action set
    Value Type Literal
    Property Data Type String
    Value application/json
    Value String Capturing Group 0
    Property Scope axis2

  8. Save the sequence, which is in XML format (e.g., SOAPtoJSON.xml ). This will be the Out sequence for your API.

  9. Click the Push all changes to the server icon shown below to commit your changes to the Publisher server.

  10. Log back into the API Publisher, select PhoneVerification API and click the Runtime Configurations menu link associated with the API and navigate to the Mediation Policies section. Click the Edit icon and engage the In and Out mediation policies that you created earlier from the respective sections.

    !!! info

    JSONtoSOAP in sequence will serve the purpose of transforming the JSON payload to SOAP before sending it to the SOAP backend. SOAPtoJSON out sequence will transform the SOAP message returned from the backend to JSON.

  11. Save the API. You have created an API, a resource to access the SOAP backend and engaged sequences to the request and response paths to convert the message format from JSON to SOAP and back to JSON. Let's subscribe to the API and invoke it.

  12. Log in to the API Devportal and Subscribe to the API and create an access token if you have not done so already.

  13. Select the PhoneVerification API, Go to the Try Out menu and expand the POST method.

  14. Click on the Try It Out and give the payload in the body parameter in JSON format and click Execute. Here's a sample JSON payload: {"request":{"PhoneNumber":"18006785432","LicenseKey":"0"}}

  15. Note that you get a JSON response to the JSON request whereas the backend accepts SOAP messages. The request and response are converted by the sequences that you engaged in.

In this tutorial, you converted a message from JSON to SOAP and back to JSON using In and Out sequences.