HTTP-RPC Interface

Summary
HTTP-RPC is a simple, non-standardized interface for Webservices.nl.
The HTTP-RPC interface can be found at the following locations, where request, response and encoding are variables and must be replaced.
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 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.
get
With the “get” request type, input parameters are passed in the URL, separated by ‘/’.
With the “serialized” request type, the method name and parameters are encoded using the PHP serialize() function.
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.
Besides the methods described in the documentation, the HTTP-RPC interface offers additional methods to retrieve meta-data on methods.

What is HTTP-RPC?

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.

Endpoint location

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

main endpoint https://ws1.webservices.nl/rpc/request-response/encoding
fallback endpoint https://ws2.webservices.nl/rpc/request-response/encoding

The variable request must be a valid Request type:

The variable response must be a valid Response type:

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.

Request and response types

Request type

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:

get The parameters are passed in the URL, separated by ‘/’.
serialized The parameters are serialized using the PHP serialize() function and passed to the interface using HTTP POST.
xmlrpc The parameters are passed as a standard XML-RPC request by using HTTP POST.

Response type

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:

serialized The response is serialized using the PHP serialize() function.
xmlrpc The response is a standard XML-RPC response.
simplexml The response is a simple XML document.

get

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

serialized

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.

xmlrpc

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

simplexml

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.

More information

Additional methods

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.

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.
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.
With the “get” request type, input parameters are passed in the URL, separated by ‘/’.
With the “serialized” request type, the method name and parameters are encoded using the PHP http://www.php.net/serialize|serialize() function.
With the “xmlrpc” request or response type, the messages are exactly as they would be when using the XML-RPC Interface.
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.
With the “simplexml” response type, the response consists of a simple XML document.