Using SOAP

Summary

Using SOAP
Step by step	Calling a method using SOAP consists of the following steps:
Create a stub using the WSDL	Some SOAP libraries need to generate some code from the WSDL, before the web service can be used.
Instantiate a client object based on the stub or WSDL	In this step, you instantiate the soap client object, or the stub that you created in the previous step.
Provide the client object with an authentication header	To call a method, you need to be authenticated.
Call a method on the client object	Call a webservice method simply like you would call any other method.
Use the result	If the call failed, you get a SoapFault.
Read more

Step by step

Calling a method using SOAP consists of the following steps:

Create a stub using the WSDL
Instantiate a client object based on the stub or WSDL
Provide the client object with an authentication header
Call a method on the client object
Use the result

Create a stub using the WSDL

Some SOAP libraries need to generate some code from the WSDL, before the web service can be used. In this step, you use the programming environment or a tool to generate some code, called the stub, which can be used to call the web service.

The WSDL is a XML file that contains the specification for this interface. Most stub generators can simply be pointed to the WSDL, and they will generate a piece of code called the stub, that can be used to call Webservices.nl methods. The URL for the WSDL can be found on the SOAP Interface pages.

In .NET, for example, you can use the “Add Web Reference wizard” or the wsdl.exe tool to generate code from the WSDL which calls the webservice. When using Axis2 under Java, you can use the WSDL2Java tool.

For languages which parse the WSDL at runtime, such as PHP, this step is not needed. If you are using PHP with the SOAP Document/Literal interface, you can download and use the github code from the testclient.

Instantiate a client object based on the stub or WSDL

In this step, you instantiate the soap client object, or the stub that you created in the previous step.

C#

myservice = new nl.webservices.ws1.Webservicesnl();

PHP

$client = new SoapClient($wsdl);

Provide the client object with an authentication header

To call a method, you need to be authenticated. Unless you are using the SOAP headerless interface, this is done by adding one of the following SOAP headers to every request:

HeaderLogin
HeaderAuthenticate

The HeaderLogin header contains the username and password. This is the easiest and fastest way to provide authentication.

The HeaderAuthenticate header contains a session token with the name “reactid”, which can be obtained by calling Authentication::login. The acquired session token remains valid for a period of ten hours and is bound to a single server. The token can be invalidated directly using Authentication::logout. Authenticating with the session token removes the need for sending username and password in every request.

Unless you are using the SOAP headerless interface, you need to provide a SOAP header for Authentication. The client object usually has some method or property by which headers can be set. In .NET, you can instantiate a HeaderLoginType object, set the username and password properties and set it as HeaderLogin property on the client object. In PHP, you can call __setSoapHeaders() with a SoapHeader object.

C#

nl.webservices.ws1.HeaderLoginType loginHeader = new nl.webservices.ws1.HeaderLoginType();
loginHeader.username = username;
loginHeader.password = password;
myservice.HeaderLogin = loginHeader;

PHP

$headerLogin = new SoapHeader(
  'http://www.webservices.nl/soap/',
  'HeaderLogin',
  array('username' => $username, 'password' => $password),
  true
);
$client->__setSoapHeaders($headerLogin);

Call a method on the client object

Call a webservice method simply like you would call any other method. Names of services can be found in the documentation. For example, to call an Address function to validate an address, you would call the addressReeksPostcodeSearch method:

PHP

$result = $client->addressReeksPostcodeSearch('2012ES30');

Use the result

If the call failed, you get a SoapFault. In some languages a SoapFault is a type of exception, which is thrown just as any other exception. The SOAP Fault contains a ‘faultstring’, which is a message explaining what went wrong, as well as an ‘errorcode’ element inside the ‘detail’ element. Only the errorcode element should be used detect and handle different types of errors, as all other error elements may be subject to change in the future. See Error Handling for more information.

If the call succeeded, you will get some object or structure with the results. The documentation describes the structure of the result.

Some clients have difficulty to distinguish a single element from an array with zero or one elements. It may be possible that your client does not always return an array where you expect it to.

C#

try
{
    result = myservice.addressReeksPostcodeSearch("2011VM18");
}
catch (SoapException e)
{
    HandleSoapFault(e);
    return;
}
System.Console.WriteLine("city: " + result.plaatsnaam);