XML-RPC Interface

Summary
XML-RPC is a protocol to call Webservices.nl methods using XML over HTTPS.
The XML-RPC interface can be found at the following locations:
Calling a method using XML-RPC consists of the following steps:
If an error occurs, you should use the X-WS-ErrorCode HTTP header to differentiate between errors.
Besides the methods described in the documentation, the XML-RPC interface offers additional methods to retrieve meta-data on methods.
These XML-RPC libraries are available:
The following example uses the OpenReact XML-RPC Client:

What is XML-RPC?

XML-RPC is a protocol to call Webservices.nl methods using XML over HTTPS.  XML-RPC is simpler than the SOAP Interface and more standardized than the HTTP-RPC Interface.  XML-RPC uses XML messages that contain self-describing data structures, and does not use XML schemas to define input and output structures.

Endpoint location

The XML-RPC interface can be found at the following locations:

UTF-8 character encoding (recommended)

main endpoint https://ws1.webservices.nl/xmlrpc/utf-8
fallback endpoint https://ws2.webservices.nl/xmlrpc/utf-8

Latin1 character encoding

main endpoint https://ws1.webservices.nl/xmlrpc/iso-8859-1
fallback endpoint https://ws2.webservices.nl/xmlrpc/iso-8859-1

Read more about Character Encoding.  The endpoints are available on HTTPS.

Calling a method

Calling a method using XML-RPC consists of the following steps:

  • Instantiate a client object.  Usually it’s enough to pass the Endpoint location to the XML-RPC constructor.  In some programming environments, you have to define the interface for the methods you want to call.
  • Call the method.  Usually, this is done by calling the method on the XML-RPC client object, just as you would call an ordinary method.  For authentication, the first parameter must be the username and the second parameter must be the password.  Following are the parameters to the method.
  • Use the result.  The XML-RPC client will already parse the XML and return an object with the result.  You should check whether the result is an error (see XML-RPC errors) and extract data from it to use in your application.

XML-RPC errors

If an error occurs, you should use the X-WS-ErrorCode HTTP header to differentiate between errors.

On error, the result will be a fault containing a ‘faultCode’ and a ‘faultString’.  The faultCode contains a numeric indication of the error.  The values are listed in the fault code specification.  The ‘faultString’ is a message explaining what went wrong.  It may be useful during testing, but should not be used for detecting specific errors, as it may be subject to change in the future.

If the XML-RPC message is valid but another error occurs, such as when specifying an invalid postcode, the faultCode is -32500 and the X-WS-ErrorCode HTTP header contains the Webservices.nl error code, such as ‘Client.Input.FormatIncorrect’.  This header should be used to differentiate between errors.

Additional methods

Besides the methods described in the documentation, the XML-RPC interface offers additional methods to retrieve meta-data on methods.  With these functions, you do not have to supply your username and password.

system.methodParameters(method) returns an associative array with parameter names as keys and parameter types as values.
system.methodHelp(method) returns documentation on a method.
system.methodSignature(method) returns the return type and the types of the parameters.
system.listMethods returns a list of available method names.
system.getCapabilities returns a list of specifications this server conforms to.

XML-RPC libraries

These XML-RPC libraries are available:

PHP OpenReact XML-RPC Client, PHP’s built-in XML-RPC, Incutio XML-RPC
.NET XML-RPC.NET
Java Apache XML-RPC

Example of a function call in PHP

The following example uses the OpenReact XML-RPC Client:

                  <?php
require('/PATH/TO/OpenReact_XmlRpc_Client/library/OpenReact/Autoload.php');
OpenReact_Autoload::register();

$client = new OpenReact_XmlRpc_Client('https://ws1.webservices.nl/address/xmlrpc/UTF-8');

var_dump($client->call('system.listMethods'));
?>
The XML-RPC interface can be found at the following locations:
If an error occurs, you should use the X-WS-ErrorCode HTTP header to differentiate between errors.