How to expose SOAP services as SOAP services via WSO2 API Manager?

Exposing SOAP services is well supported by WSO2 ESB. However, if you would like to have features such as design & prototype APIs, publish & govern API use, control access & enforce security, create a store where anyone can come, play around & subscribe to APIs, manage developer community and monitor API usage etc, then WSO2 API Manager is the ideal product. See here for a complete set of features offered by WSO2 API Manager.

In this post, we will see how you can expose a SOAP service as a SOAP service via WSO2 API Manager 1.9.0.

1. If you don't have any SOAP service, find a public SOAP service in http://www.service-repository.com

2. In this post, we will use StockQuote SOAP service from the above public service repository. Below are the details we should have in order to publish a SOAP service via WSO2 API Manager.

StockQuote SOAP WSDL - http://www.webservicex.com/stockquote.asmx?WSDL
StockQuote SOAP Endpoint - http://www.webservicex.com/stockquote.asmx

3. Download WSO2 API Manager 1.9.0 or latest version from here and start it. If you are new to WSO2 API Manager, visit the quick start guide. 

4. Login to API Publisher (https://localhost:9443/publisher)

5. Click on "Add" under "APIs" from the left menu

6. Click on "I have a SOAP Endpoint" option, provide your WSDL URL and click on "Start Creating"

7. In the "Design API" page, fill in the general details and click on "Next: Implement"

8. Click on "Managed API".

9. Fill in "Production Endpoint" and "Sandbox Endpoint" and click on "Next: Manage". If your endpoint is secured, have a look at this to learn how to configure a secured backend endpoint in WSO2 API Manager.

10. Select "Tier Availability" and "Transports" under "Configurations" and click "Save & Publish". You have now successfully published a SOAP service as a SOAP service via WSO2 API Manager.

11. Login to API Store (https://localhost:9443/store)

12. Click on your API and you will see a WSDL is published under "Overview" space of the API. Click "Download WSDL" and save it in your machine. Later we will use SoapUI to load this WSDL and invoke the API.

13.  Subscribe to the API using one of your Application and go to "My Subscriptions" page.

14. Click on "Generate keys" to generate consumer key & secret and access token. You will need this access token to invoke the API unless you have disable security to your API when publishing the API. See here to learn how to do that.

15. Create a new SOAP project in SoapUI using the WSDL you have downloaded in step 12.

16. Send a request and you will get following error. Reason is you haven't sent the access token as a bearer token when invoking the API.

17. Add a header "Authorization" and set the value as "Bearer #access-token". Replace #access-token with the access token you generated step 14.

18. Send the request and you will get the response.

As you can see, it is very straightforward to expose a SOAP service as a SOAP service via API Manager.

WSO2 API Manager - Using Custom Handler or Mediation Extensions for Message Transformation?

Custom Handlers and Mediation Extensions are some of the extension points which you can use to extend the functionality of WSO2 API Manager. When it comes to message transformation, it is recommended to use Mediation Extensions over Custom Handlers due to following reasons.

• If you want to engage a custom handler to all of your APIs, then you need to add it to all the APIs manually unless you modify velocity_template.xml to include the custom handler. If you are changing velocity_template.xml, then already published APIs won't have any impact. You need to republish those APIs to get the effect. On the other hand, if you copy a global mediation extension into AM, it will be engaged with all the APIs immediately.

• If you decided not to do the transformation, then reverting changes is just a matter of removing mediation extensions from AM. On the other hand, if you are using a custom handler, then you have to remove the custom handler from all the APIs manually. Or else, you need to modify the velocity_template.xml and need to republish all your APIs.

• If you are using a custom handler, it will be a maintenance overhead when it comes migration and all. If you are migrating, then you need to rebuild your custom handler with correct dependencies.

However, there might be some situations where we can't actually implement our usecase using inbuilt features. Then we should definitely go for a custom handler. For example, DBLookup mediator won't return multiple rows. Hence, while message transformation, if you want to retrieve multiple rows from the database, then you need to go for a custom handler.

As you can see, choice depends on many factors. As a simple rule, we need to use the mediation extensions wherever possible for message transformations within API Manager.

Capturing/Decoding messages with JWT using wire logs in WSO2 API Manager 1.7.0

This is intended for the users who have configured WSO2 API Manager 1.7.0 with JWT and wants to see the messages with JWT. If you haven’t configured it, please refer this

1. Enable debug logs for the following loggers in WSO2APIM_HOME/repository/conf/log4j.properties file 

       log4j.category.org.apache.synapse.transport.nhttp.wire=DEBUG

       log4j.category.org.apache.synapse.transport=DEBUG

2. Restart the WSO2 API Manager if already started

3. Access your API and have a look at carbon logs

4. You will get something similar to the following log

[2014-11-30 22:09:22,610] DEBUG - headers http-outgoing-2 >> X-JWT-Assertion: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5tSm1PR1V4TXpabFlqTTJaRFJoTlRabFlUQTF
ZemRoWlRSaU9XRTBOV0kyTTJKbU9UYzFaQT09In0=.eyJpc3MiOiJ3c28yLm9yZy9wcm9kdWN0cy
9hbSIsImV4cCI6MTQxNzM2NjQ2MTk5OCwiaHR0cDovL3dzbzIub3JnL2NsYWltcy9zdWJzY3JpYmV
yIjoicmFqa3VtYXIiLCJodHRwOi8vd3NvMi5vcmcvY2xhaW1zL2FwcGxpY2F0aW9uaWQiOiIxIiwiaHR0
cDovL3dzbzIub3JnL2NsYWltcy9hcHBsaWNhdGlvbm5hbWUiOiJEZWZhdWx0QXBwbGljYXRpb24iLC
JodHRwOi8vd3NvMi5vcmcvY2xhaW1zL2FwcGxpY2F0aW9udGllciI6IlVubGltaXRlZCIsImh0dHA6Ly9
3c28yLm9yZy9jbGFpbXMvYXBpY29udGV4dCI6Ii9waG9uZXZlcmlmeSIsImh0dHA6Ly93c28yLm9yZy
9jbGFpbXMvdmVyc2lvbiI6IjEuMC4wIiwiaHR0cDovL3dzbzIub3JnL2NsYWltcy90aWVyIjoiVW5saW1pd
GVkIiwiaHR0cDovL3dzbzIub3JnL2NsYWltcy9rZXl0eXBlIjoiUFJPRFVDVElPTiIsImh0dHA6Ly93c28yL
m9yZy9jbGFpbXMvdXNlcnR5cGUiOiJBUFBMSUNBVElPTiIsImh0dHA6Ly93c28yLm9yZy9jbGFpbX
MvZW5kdXNlciI6InJhamt1bWFyQGNhcmJvbi5zdXBlciIsImh0dHA6Ly93c28yLm9yZy9jbGFpbXMvZ
W5kdXNlclRlbmFudElkIjoiLTEyMzQiLCAiaHR0cDovL3dzbzIub3JnL2NsYWltcy9lbWFpbGFkZHJlc3Mi
OiJyYWprdW1hcnJAd3NvMi5jb20iLCAiaHR0cDovL3dzbzIub3JnL2NsYWltcy9naXZlbm5hbWUiOiJtb2
1vIiwgImh0dHA6Ly93c28yLm9yZy9jbGFpbXMvbGFzdG5hbWUiOiJtb20iLCAiaHR0cDovL3dzbzIub3J
nL2NsYWltcy9yb2xlIjoiSW50ZXJuYWwvc3Vic2NyaWJlcixJbnRlcm5hbC9ldmVyeW9uZSJ9.eczrlpBg3
+38Y90voBIhei3wXMZqZWV5z4q4nSQoUPPlUYXAo6UGmsiwBkT17BivS16K0I69tGwpxKzju/Tg8slT
06bLVmOwIeFtMH86HLh/VPKqnZ0WKgsZw5fFxccIYDgIfnzo8Gg+x9+tL+R2i71e5EOc7098FXZOXH
nlYm0=

5. As you can see, this is the JWT token in encoded format. The above message contains three parts separated by dots. We can decode this message and see what it represents. You can go https://www.base64decode.org/  and decode this message party by part.

6. If you copy paste the first part of the message (blue) into the decoder, you will get something like below

 And that contains JWT headers.

7. If you copy paste the second part of the message (pink), into the decoder, you will get something like below

 
 And that contains JWT claims set.

 8. That’s it. You have decoded and viewed the end user details that have been sent to the back end.

WSO2 API Manager - How to send additional headers in Swagger API Console?

WSO2 API Manager's Swagger API Console allows you to send authorization header by default. If you want to send additional headers, follow these steps.

* Go to the publisher and click on your API.
* Click on Docs.

* Click on Edit Contents of swagger API definition. You will get swagger API definition editor

* Under parameter section of the each HTTP method, you can add what ever parameters you want. It can be headers, body etc.

* For example, if you want to add tenant and enterprise headers to PUT method, you will add the following entries under parameters section of PUT method of your API.

* And then you should add these two headers under Access-Control-Allow-Headers of CORS configuration in api-manager.xml, like below.

* Finally restart the API Manager if already started.

* Go to the API Console in store and click on PUT method

Now you should be able to send additional headers from API Console.

WSO2 API Manager's Swagger API Console does not return any results?

When you click “Try it out!” option, sometimes you will see nothing happens other than some dots are moving.

There can be several reason for this problem.

First you need to verify whether CORS configurations are correct in api-manager.xml
It is clearly explained here. Please make sure your settings are correct according to this guide.

If you are accessing the store via HTTPS, you will not be able to use API Console most of the times.

Reason is swagger base path is set to HTTP production endpoint by default. So swagger client can't connect to it.

You can change the swagger base path as explained here.

* Go to publisher and click on your API.

* Click on Docs

* Click Edit Contents of swagger API definition. You will get swagger API definition editor

* You will see that the base path is set to HTTP production url like http://10.100.5.84:8280/phoneverify/1.0.0

* Change it to HTTPS production url like https://10.100.5.84:8243/phoneverify/1.0.0

* Please note that the ports are different in each url.

* Save and close the swagger API definition editor

* Now click on “Try it out!” option from store, you will get response

There you go! You got the response!