HTTP-RPC Interface

HTTP-RPC is a simple, non-standardized interface for Webservices.nl.  By requesting a specific URL or posting data over HTTPS, this interface offers data access over a non-standardized HTTP protocol.  There are no libraries available for this interface.  It is simple to implement, especially for methods with a few simple parameters.

The HTTP-RPC interface can be found at the following locations, where request, response and encoding are variables and must be replaced.

The variable request must be a valid Request type:

• get
• serialized
• xmlrpc

The variable response must be a valid Response type:

• serialized
• xmlrpc
• simplexml

The variable encoding must be a valid Character Encoding:

• utf-8
• iso-8859-1

For example, a complete URL would look like this: https://ws1.webservices.nl- /rpc- /get-simplexml- /utf-8

The endpoints are available on HTTPS.

The HTTP RPC interface allows the user to define the encoding for both the request and response, by supplying the request and response types in the URL.  A request can be supplied to the HTTP/RPC interface in one of the following ways:

The HTTP RPC interface allows the user to define the encoding for both the request and response, by supplying the request and response types in the URL.  The response can be encoded in one of the following ways:

With the “get” request type, input parameters are passed in the URL, separated by ‘/’.

Parameters

• method name (e.g. addressReeksPostcodeSearch)
• user name
• password
• method parameters

For example, the following URL will return a simplexml result for the function addressReeksPostcodeSearch, with parameter 2012ES30:

https://ws1.webservices.nl- /rpc- /get-simplexml- /utf-8- /addressReeksPostcodeSearch- /username- /password- /2012ES30

With the “serialized” request type, the method name and parameters are encoded using the PHP serialize() function.  The request should have the following structure:

 array(
   'methodName' => $methodName,
   'params' => array($username, $password, $parameter1, $parameter2, ...)
)

Note that the first two parameters are the username and password, and these are followed by the method parameters.  To leave a parameter empty, pass the empty string.

Similarly, with the “serialized” response type the response exists of an associative array serialized with the PHP serialize() function.

If an error occurs, you should use the X-WS-ErrorCode HTTP header to differentiate between errors.  On error, the de-serialized response will hold an stdClass object with the public properties code and message.  If the request 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.

With the “xmlrpc” request or response type, the messages are exactly as they would be when using the XML-RPC Interface.

With the “simplexml” response type, the response consists of a simple XML document.

If an error occurs, you should use the X-WS-ErrorCode HTTP header to differentiate between errors.  On error, the response will be a <fault> element within the <response> element.  This fault element contains both a <faultCode> element and a <faultString> element.  If the request 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.

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

• Error Handling
• Implementing fallback
• Troubleshooting