Web Services

Introduction

Web services are web applications exposing an HTTP interface. A request to a web service represents an activity that produces results directly, triggers lengthy operations, or retrieves the current status from a database or a process running asynchronously. In any case, a caller should wait for the web service to return its result to decide on further action.

WDK web services accept parameters via GET parameters within the request URL and via POST parameters in the POST header. Web services should ALWAYS ignore cookies being sent by a browser.

WDK web services can render their HTTP response as XML, JSON, HTML, different CSV variants and other formats.

The response of a web service is an associative and numeric multilevel array. The root node of this tree is called "WEBSERVICE". The "RESULT" subnode contains the actual data being returned. If an error occured the node "ERROR" contains a string error code.

Consumption

Default Parameters

WDK web services support a number of parameters by default. Additional parameters depend on the command being requested.
command
The "command" parameter specifies the command to be executed. Some may refer to this as an 'action' or 'route' to a web service. All web services support the "help", "selfcheck" and "install" commands. Each web service implements its own set of commands though. Use the "help" command to find out which commands are supported.
accesscode
A secret token to be supplied to authorize the consumer. This parameter should NOT be supplied as an URL parameter as it may be stored in web server log files.
format
The format in which the response of a web service should be rendered. The following formats are supported by default: "xml", "jsonpretty", "json", "printr", "html", "csv" and "csvpath".
csvpath
If the format "csv" is used, the "csvpath" parameter can be used to specify the node of the result tree that should be contained in the response. The "csv" format only allows the transfer of tables but does not allow the transfer of complex tree structures.
trace
Like all WDK based web applications all web services support the "trace" parameter. If set to "1" the result contains trace output collected from its own activity and all subsequent web service calls.

Default Commands

help
The help command provides documentation on the web service
selfcheck
As the name suggests the selfcheck command performs internal tests indicating if the web service is fully functional.
install
The install command performs first-time initialization of a web service. Web services encapsulating a database may create tables during the install command.

Formats

Different formats serve different use cases. Check out what suits best.
Format Supported by Parse speed Response size Browser based debugging
xml Wide range of systems SLOW WEAK NEUTRAL
csv Wide range of systems FASTEST BEST LIMITED
csvpath WDK specific FAST WEAK LIMITED
json Wide range of systems FAST GOOD WEAK
jsonpretty Wide range of systems FAST MEDIUM GOOD
html All browsers Not relevant WEAK IDEAL
printr All browsers Not relevant MEDIUM BEST