SOAP API via SOAP UI
An example of how to call the API using SOAP UI
What is SOAP UI?
SOAP UI is a free tool developed by Smart Bear for testing and calling SOAP based services. A lot of companies use this tool for calling and automatically testing SOAP services. We use it at W2 to explore and test SOAP services and this page gives an example of how to perform a few simple calls against a W2 UAT server.
Step One: download and install
SOAP UI can be downloaded here. You will only need the free version for this demo.
Step Two: Set up your first project
Run SOAP UI and, after you get through all the start screens, select File -> New Workspace. Name it W2 Demo (or a similar name) and save it to an appropriate location.
You should see a screen a bit like the following with your new workspace on the left:
Click on File -> New SOAP Project:
You will see a screen a bit like this:
In the Project Name box enter a sensible name. I am calling it W2 DEMO SIS.
In the Initial WSDL enter the URL of the UAT wsdl:
The TestSuite is a feature of SOAP UI where you can set up Test assertions that can be used in automatic testing. We won’t be going in to this in this example but it is a very useful feature that you may want to explore. There are many other examples on the Smart Bear Site.
Click OK to generate the test. You should get something like this:
You can also use the default Request 1 or to make a new request right click on the KYCCheck node and select New Request and then give the request a name:
This should create an example SOAP envelope containing comments and question marks. The Request Page details this further.
For this example we are going to call a bundle that is already set up on the UAT server called DEMO_KYC_SIS, which just contains the SIS Plus service.
Step Three: Call the API
You can start editing the auto generated request. Start by entering “DEMO_KYC_SIS” in the <BundleName> element.
You can get rid of most of the QueryData except for the <NameQuery> element. Type Robert Mugabe in here.
You can remove the <QueryOptions> element and the <UploadedFiles> element.
In the <ServiceAuthorisation> section enter your <APIKey> and an optional <ClientReference>. The rest of the elements can be removed.
You can also get rid of the <!–Optional:–> comments. They don’t do anything and don’t affect the service but they just look untidy.
Quick Tip: you can press ALT + F to tidy up the response.
You should end up with something like this:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="http://tempuri.org/" xmlns:neur="http://schemas.datacontract.org/2004/07/NeuromancerLibrary.DataContracts" xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays"> <soapenv:Header/> <soapenv:Body> <tem:KYCCheck> <tem:serviceRequest> <neur:BundleData> <neur:BundleName>DEMO_KYC_SIS</neur:BundleName> </neur:BundleData> <neur:QueryData> <neur:NameQuery>Robert Mugabe</neur:NameQuery> </neur:QueryData> <neur:ServiceAuthorisation> <neur:APIKey>YOUR API KEY GOES HERE</neur:APIKey> <neur:ClientReference>Testing W2 services</neur:ClientReference> </neur:ServiceAuthorisation> </tem:serviceRequest> </tem:KYCCheck> </soapenv:Body> </soapenv:Envelope>
Click on the green arrow to call the service, or press Alt + Enter.
Step Four: Check The Response
If at this point you get any errors contact W2 support with the error message.
Lets look at the response in more detail.
You can see in the <ClientProvidedData> section the references you sent with the service.
In the <ProcessRequestResult> section you can see two sections <ServiceResult> and <TransactionInformation>.
The <ServiceResult> section contains a placeholder for every service we have, if you expand this section and scroll down to the <SISPlusCheckResult> section you will see the result of the service call. You should see several <CheckMatch> elements with details of people that match the name query.
The <TransactionInformation> element contains meta data and interpret data about each service you have called it will probably look something like this:
<b:TransactionInformation> <b:InterpretResult>Fail</b:InterpretResult> <b:ServiceCallReference>2076e123-819e-4fa1-a2d8-c1041fa37284</b:ServiceCallReference> <b:ServiceTransactions> <b:ServiceTransactionInformation> <b:FailedOverTo i:nil="true"/> <b:HaltTriggered>false</b:HaltTriggered> <b:Service>SISPlusCheck</b:Service> <b:ServiceInterpretResult>MultipleResults</b:ServiceInterpretResult> <b:ServiceTransactionResult>Success</b:ServiceTransactionResult> <b:ServiceTransactionResultMessage i:nil="true"/> <b:ServiceValidationDetails i:nil="true"/> <b:ValidationResult>Pass</b:ValidationResult> </b:ServiceTransactionInformation> </b:ServiceTransactions> </b:TransactionInformation>
In this example there is only one <ServiceTransactionInformation> element. For bundles that have more than one service there will be one for every service call. This element contains meta data about the service call you can find more information on the Response page.
The <InterpretResult> element contains the overall interpretation result for the service call. In this case it says Fail because we have configured this bundle to fail and halt if the individual is found on the Sanctions List. This can be configured differently for each bundle. Talk to W2 Support for more information
Example Two: Sandbox
Most of our services expose a Sandbox version of the service. This means that you can call the service with a known set of query data and get a stock response. This is quite useful for testing the service out. Sandbox calls are not chargeable and won’t leave a foot print.
Step One: New Request
For this example create a new request in SOAP UI as we did above and call it “DEMO PEP SANDBOX”. We are going to use a different bundle for this example called DEMO_KYC_PEP, which contains the PEPDesk service (Politically Exposed Persons).
Step Two: Fill in the Request
As we did for example one we are going to create a request object.
- In the <BundleName> element enter DEMO_KYC_PEP.
- Remove all the <!–Optional–> tags.
- Remove all the <QueryData> elements except for <NameQuery>.
- Remove all of the <UploadedFiles> elements.
- In the <NameQuery> element type David Cameron.
- Fill in the <ServiceAuthorization> element as in Example One.
- In the QueryOptions set the <Key> to Sandbox and the <Value> to true. This is important as this is what makes it a sandbox call.
It should look something like this:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="http://tempuri.org/" xmlns:neur="http://schemas.datacontract.org/2004/07/NeuromancerLibrary.DataContracts" xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays"> <soapenv:Header/> <soapenv:Body> <tem:KYCCheck> <tem:serviceRequest> <neur:BundleData> <neur:BundleName>DEMO_KYC_PEP</neur:BundleName> </neur:BundleData> <neur:QueryData> <neur:NameQuery>David Cameron</neur:NameQuery> </neur:QueryData> <neur:QueryOptions> <arr:KeyValueOfstringstring> <arr:Key>Sandbox</arr:Key> <arr:Value>true</arr:Value> </arr:KeyValueOfstringstring> </neur:QueryOptions> <neur:ServiceAuthorisation> <neur:APIKey>XXXXXXXXX</neur:APIKey> <neur:ClientReference>Testing W2 services</neur:ClientReference> </neur:ServiceAuthorisation> </tem:serviceRequest> </tem:KYCCheck> </soapenv:Body> </soapenv:Envelope>
Step Three: Call the Service
Press the green arrow to call the service.
The response will be very similar to the response from Example One, except in the <TransactionInformation>, the <ServiceTransactionResultMessage> will say “This call was generated using sandbox mode”. If you check the documentation for the PEPDesk Service you will see that the sandbox response is the same as the pre-configured response from the sandbox.