Exposing an Integration SOAP Service as a Managed API

Managed APIs refer to the APIs that are managed using MWARE ESB, namely REST APIs, GraphQL APIs, SOAP APIs, and Streaming APIs. This guide explains how to create a Proxy Service (SOAP backend) for the integration solution, generate relevant metadata for the corresponding Proxy service, publish the WSDL definition in the MWARE ESB Service Catalog and then creating a SOAP Pass-Through API.

Also, this demonstrates how the integration components and API management components of MWARE ESB work together to enable API-led integration.

Let's get started!

Follow the steps given below to build this use case and try it out.

Note

For more information on generating metadata artifacts if you are using an older Integration Studio workspace, see Generating Service Catalog Metadata Artifact.

Step 1: Develop the integration service

Follow the instructions given in this section to create and configure the required artifacts.

  1. Download the relevant ESB Integration Studio based on your operating system.
  2. Open ESB Integration Studio.

  3. Click New Integration Project in the Getting Started tab as shown below.

    This will open the New Integration Project dialog box.

  4. Enter ProxyServiceSample as the project name and select the following check boxes to create the required modules.

    • Create ESB Configs
    • Create Composite Exporter

  5. Click Finish.

    You can see the projects listed in the Project Explorer as shown below:

    Note

    A resources folder is created in the ProxyServiceSampleConfigs project. This folder holds the metadata YAML files of the created proxy services. These YAML files will be uploaded to the Service Catalog later in this tutorial.

  6. Create a Proxy Service artifact.

    1. In the project explorer, right-click ProxyServiceSampleConfigs and click New -> Proxy Service.
    2. Follow the Using a Simple Proxy Service to create the StockQuoteProxy Proxy Service.

    3. Enter the details given below to create a new Proxy Service.

      Property Value Description
      Name StockQuoteProxy The name of the Proxy Service.
      Save location ProxyServiceSampleConfigs This is the ESB Config module where the artifact will be saved.

    4. Click Finish.

  7. Open the Source view of the StockQuoteProxy that you created and edit the integration solution.

    <?xml version="1.0" encoding="UTF-8"?>
<proxy name="StockQuoteProxy" startOnLoad="true" transports="http https" xmlns="http://ws.apache.org/ns/synapse">
    <target>
        <endpoint>
            <address uri="http://localhost:9000/services/SimpleStockQuoteService"/>
        </endpoint>
        <inSequence>
            <log description="Request Log" level="custom">
                <property name="Message" value="&quot;You have successfully invoked the StockQuoteProxy&quot;"/>
            </log>
        </inSequence>
        <outSequence>
            <send/>
        </outSequence>
        <faultSequence/>
    </target>
    <publishWSDL uri="file:/path/to/sample_proxy_1.wsdl"/>
</proxy>

When the StockQuoteProxy is created, the following new file is created in the metadata folder.

StockQuoteProxy_proxy_metadata.yaml This file contains the metadata of the integration service you created in the previous step.

Step 2: Configure service metadata

Let's update the metadata of the integration service.

  1. Open the StockQuoteProxy_proxy_metadata.yaml file from the project explorer.

  2. Update the following values in the file.

    Parameter Value Description
    description Response a sample payload from the service Explain the purpose of the Proxy Service.
    serviceUrl http://localhost:8290/services/StockQuoteProxy This is the URL of the API when it gets deployed in the Micro Integrator. You (as the integration developer) may not know this URL during development. Therefore, you can parameterize the URL to be resolved later using environment variables. By default, the {MI_HOST} and {MI_PORT} values are parameterized with placeholders. In the runtime, if placeholder values are not defined server default hostname and http/https listener ports will be used.

    You can configure the serviceUrl in the following ways:
    • Add the complete URL without parameters. For example: http://localhost:8290/services/StockQuoteProxy.
      Let's use this option for this tutorial.
    • Parameterize using the host and port combination. For example: http://{MI_HOST}:{MI_PORT}/services/StockQuoteProxy.
    • Parameterize using a preconfigured URL. For example: http://{MI_URL}/services/StockQuoteProxy.

    Tip

    See the Service Catalog API documentation for more information on the metadata in the YAML file.

  3. Important: Be sure to change the serviceUrl from HTTPS to HTTP. This is required because the StockQuoteProxy is not secured.

  4. Leave the default values for the remaining parameters.

Step 3: Configure the Micro Integrator

The Micro Integrator contains a client application, which automatically publishes artifacts to the Service Catalog in the API Publisher portal.

Let's enable this client for the embedded Micro Integrator of ESB Integration Studio.

  1. Click the Embedded Micro Integrator Configuration () icon on the upper menu to open the dialog box.

  2. Uncomment the [[service_catalog]] section as shown below and change the APIM server configurations accordingly.

    Tip

    The default username and password for connecting to the API gateway is admin.

    [[service_catalog]]
apim_host = "https://localhost:9443"
enable = true
username = "admin"
password = "admin"

  3. Optionally, you can encrypt the username and password for better security:

    1. Update the configuration as shown below. 

      [secrets]
userName = "[admin]"
password = "[admin]"

[[service_catalog]]
apim_host = "https://localhost:9443"
enable = true
username = "$secret{username}"
password = "$secret{password}"

    2. Click Encrypt Secrets.

    Tip

    See Encrypt static (embedded) server secrets for details.

  4. Save the configurations.

  5. Optionally, inject environment variables to your Micro Integrator. Default in runtime, if placeholder {MI_HOST} and {MI_PORT} values are not defined server default hostname and http/https listener ports will be used.

    If you chose to parameterize the serviceUrl in the metadata file, you must inject the parameterized values as environment variables. Shown below are example placeholder values that you may have used in the serviceUrl followed by the corresponding environment variables. 

    {MI_HOST}  :  localhost
{MI_PORT}  :  8290 #for http protocols. Otherwise 8253
{MI_URL}   :  localhost:8290 #for http protocols. Otherwise localhost:8253

    Tip

    See the instructions on injecting environment variables to the embedded Micro Integrator.

Step 4: Package the artifacts

Package the artifacts in your composite exporter module to be able to deploy the artifacts in the server.

  1. Open the pom.xml file of the ProxyServiceSampleCompositeExporter module.

  2. Ensure that the following artifact is selected in the POM file.

    • StockQuoteProxy

  3. By default, the Publish to Service Catalog checkbox is enabled. If not, please select the checkbox in the wizard so that it will include metadata files of the selected artifacts.

  4. Save the changes.

Step 5: Start the ESB runtime

Let's start the ESB runtime before starting the Micro Integrator.

  1. Download and set up MWARE ESB.
  2. Start the server.

Step 6: Build and run the service

Let's deploy the packaged artifacts in the embedded Micro Integrator:

Info

When you do this step:

  1. The Micro Integrator first reads the metadata files.
  2. If you used placeholders in the metadata file, they are replaced with environment variable values.
  3. It gets the WSDL 1 definition of the deployed proxy service from the 'serviceUrl' as in 'Step 2: Configure service metadata' and ZIP file is created along with the metadata file.
  4. Finally, it uploads the metadata to the API management runtime.
  1. Right-click the composite exporter module and click Export Project Artifacts and Run.
  2. In the dialog box that opens, confirm that the required artifacts from the composite exporter module are selected.
  3. Click Finish.

The artifacts are deployed in the embedded Micro Integrator and the Micro Integrator starts. The integration service is also deployed in the Service Catalog during server startup. You will see the following in the server start-up log.

Successfully updated the service catalog

Step 7: Create and Deploy the Proxy Service as a SOAP Pass-Through API

Create the API

Let's expose the integration service as a managed API.

  1. Sign in to the API Publisher portal: https://localhost:9443/publisher.

    Tip

    Use admin as the username and password.

  2. You can also click the hamburger icon on the upper-left and click Services to see the available services.

    open service catalag

  3. Open StockQuoteProxy from the above list.

    API created from service catalog

  4. Click Create API in the above screen to open the Create API dialog box.

    create api dialog box

  5. Specify an API name, context, and version, and then click Create API.

    Tip

    You will find these values already populated based on the information in the integration service.

You can now see the new API's overview page.

new api view

Note

  • You can use the left-hand navigation to explore the new API.
  • Click Endpoints in the left-hand navigator. You will see that the new API uses the integration service deployed in the Micro Integrator as the endpoint (backend). endpoint view

Select business plans

Let's allocate some business plans for the API.

  1. Go to the API overview and click Business Plan.

    click to add business plan

  2. Select at least one business plan for the API and save.

    add business plans to api

Deploy API in the Gateway

Let's deploy the API in a gateway environment.

  1. Go to the API overview and click Deploy.

    Tip

    This opens the Deployment tab in the left-hand navigator.

    open the deployment options

  2. Click Default to specify the gateway environment and host.

    Tip

    This setting deploys the API in Production as well as Sandbox gateways. Find out more about gateway environments.

    select gateways for the deployment

  3. Optionally, you can add a description.

  4. Click Deploy.

You will now see the deployment as the first revision of the API:

api first revision

Step 8: Publish the API

Go to the API overview in the Publisher portal and click Publish for the StockQuoteProxy as shown below.

The API is now available in the Developer portal for consumers to access.

Step 9: Subscribe to the API

Now, let's assume you are an API consumer who wants to use the API. As a consumer, you need to first subscribe to the API.

  1. Sign in to the Developer portal: https://localhost:9443/devportal/apis.

    Tip

    Use admin as the username and password.

  2. Go to the API tab. The StockQuoteProxy is listed as shown below.

  3. Select the StockQuoteProxy to open the API overview.

  4. Go to the Subscriptions tab and subscribe using the DefaultApplication as shown below.

Tip

For detailed instructions, see Subscribe to an API.

Step 10: Use the SOAP Pass-Through API

Before you begin

Let's start the back-end service.

  1. Download the back-end service.
  2. Extract the downloaded zip file.
  3. Open a terminal, navigate to the axis2Server/bin/ directory inside the extracted folder.

  4. Execute the following command to start the axis2server with the SimpleStockQuote back-end service:

    sh axis2server.sh
    axis2server.bat

Generate access token

When you consume an API from the marketplace, your access to the API is authenticated. Therefore, the DefaultApplication that you used for subscribing to the API should get an access token for the gateway environment in which the API is deployed. Since the StockQuoteProxy is deployed in the Production gateway, you must generate PROD keys.

  1. Go to the Subscriptions tab for the StockQuoteProxy in the Developer portal.

  2. Click PROD KEYS for the DefaultApplication.

  3. Click Generate Keys (at the bottom of this view) to apply a consumer key and secret as shown below.

    Note

    The application may already have a consumer key and secret generated. In this case, you can skip this step.

  4. Click Generate Access Token in the above view to generate the access token.

  5. Save the generated token.

Try out the service

Now, let's test the use case by sending a simple client request that invokes the service.

  1. Click Try Out for the StockQuoteProxy in the Developer portal as shown below.

  2. Enter the following details.

    Security Type Select OAuth as the security type.
    Applications Select DefaultApplication from the list of application.
    Key Type Select Production as the key type. This means that the production gateway (environment) is used.
    access.token Add the access token you generated for the DefaultApplication. You can also click GET TEST KEY to generate a test token.
    Gateway Select Default as the gateway.

  3. Expand the / POST resource and click Try it out.

  4. Let's specify 'urn:getQuote' as the SOAP Action.
  5. Let's input the following payload as the SOAP Request. 
        <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://services.samples" xmlns:xsd="http://services.samples/xsd">
        <soapenv:Header/>
        <soapenv:Body>
          <ser:getQuote>
             <ser:request>
                <xsd:symbol>IBM</xsd:symbol>
             </ser:request>
          </ser:getQuote>
        </soapenv:Body>
    </soapenv:Envelope>

  6. Click Execute.

You will get the response message from the StockQuoteProxy service:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Header/>
    <soapenv:Body>
        <ns:getQuoteResponse xmlns:ns="http://services.samples">
            <ns:return xsi:type="ax21:GetQuoteResponse" xmlns:ax21="http://services.samples/xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                <ax21:change>3.9976027101114964</ax21:change>
                <ax21:earnings>13.346364457377131</ax21:earnings>
                <ax21:high>-73.39500514990955</ax21:high>
                <ax21:last>73.6913265107944</ax21:last>
                <ax21:lastTradeTimestamp>Fri Sep 24 22:10:56 IST 2021</ax21:lastTradeTimestamp>
                <ax21:low>-71.88761385784731</ax21:low>
                <ax21:marketCap>4.3004624870633185E7</ax21:marketCap>
                <ax21:name>IBM Company</ax21:name>
                <ax21:open>-71.86467758088759</ax21:open>
                <ax21:peRatio>24.390401836247552</ax21:peRatio>
                <ax21:percentageChange>-5.715833533678435</ax21:percentageChange>
                <ax21:prevClose>-69.93910313442652</ax21:prevClose>
                <ax21:symbol>IBM</ax21:symbol>
                <ax21:volume>8029</ax21:volume>
            </ns:return>
        </ns:getQuoteResponse>
    </soapenv:Body>
</soapenv:Envelope>

Now, check the Console tab of ESB Integration Studio and you will see the following message:

INFO - LogMediator Message = "You have successfully invoked the StockQuoteProxy"

Tip

For detailed instructions see Invoke an API using the Integrated API Console.

Top