Developer's Guide > Web Service Interface Principles

Web Service Interface Principles

Each PTV xServer module defines a services class that contains a set of related web service operations. Web services can be accessed using HTTP/SOAP or HTTP/JSON protocols.

SOAP and JSON over HTTP

Beginning with PTV xServer 1.16, PTV xServer web services support both SOAP and JSON messages. Both protocols have their advantages and disadvantages. For web applications based on Javascript/HTML5, JSON is much easier to use, while for large scale enterprise integration, good points can be made for the SOAP protocol. Both protocols are viable and both will be supported equally well.

The JSON-based web interfaces look like they follow the popular REST architectural style. From a design standpoint, a pure REST style is not a natural match for PTV xServer: there are lots of resources, but only few could be directly addressed, and the PTV xServer is not a CRUD system, so most of the REST vocabulary is not used. The chosen hybrid approach of a REST-like RPC can be easily mixed with pure REST services. From the standpoint of a pragmatic engineer, the distinction is moot anyhow: you can send data in JSON format with a plain http request and will receive a response in JSON format - and that's that.

Web Service End Points

Web service end points follow a certain URL schema. For SOAP, that schema is:

http(s)://<hostname>:<port>/<modulename>/ws/<ServiceName>

JSON end points use the following schema:

http(s)://<hostname>:<port>/<modulename>/rs/<ServiceName>/<operation>

HTTP Requests

PTV xServer services are accessed with HTTP requests using the POST method.

There are some useful standard and custom HTTP request and response header fields that influence PTV xServer behaviour or provide extra meta information. The following table describes these fields:

Direction	Field	Semantics
Request	`content-type`	Use `application/soap+xml;charset=utf-8 for SOAP, or application/json;charset=utf-8` for JSON.
	`username`	A username to be checked against the mappings in `users.properties`
	`password`	The password (in plain text) to be matched with the user.
	`accept-encoding: gzip`	If the accept-encoding field contains the gzip-value, the PTV xServer may send compressed responses, i.e. the response content is a gzip-Stream.
	`features`	A comma separated list of licensed service names, e.g. `XRoute.calculateRoute, XLocate.findAddress`. If the called service name is not in the list the PTV xServer will throw an `XServiceException`. This feature can serve as a base for 3rd party licensing hooks.
	`x-tenant`	A tenant name that serves as namespace for distance matrix ids (PTV xDima Server and PTV xTour Server).
	`xserver-module`	Sends a request to a dedicated module process. This feature has be enabled with the configuration property enableModuleMonitoringRequests.
Response	`content-type`	Will returned as text/xml for SOAP (SOAP version is still 1.1), and `application/json` for JSON.
	`xserver-host`	If the configuration property addHostinfoToResponse is set to true, this field will be added to the response and will contain the name of the server hosting the PTV xServer.
	`xserver-ip`	If the configuration property addHostinfoToResponse is set to true, this field will be added to the response and will contain the ip addresses of all interfaces of the server computer.
	`content-encoding: gzip`	This field will contain the gzip value if the server sends the response in compressed form.

Activating Message Compression

HTTP compression can safe significant network bandwidth (up to 90%) and is recommended: With usual network latency and limited network bandwidth, time and network resource benefits far surpass the minor overhead of the compression and decompression algorithms.

The PTV xServer will accept compressed requests and send compressed responses if the client has indicated acceptance by sending the appropriate headers.

Up to date PTV client classes bundled with PTV xServer will send these headers by default. To deactivate the compression on the java clients add this line before creating a new client.

System.setProperty("com.ptvag.xserver.client.gzip.disabled", "true");

Clients generated from WSDL or by other means must explicitly activate the compression. For JAX-WS-based Java clients, the following code snippet can be used:

XRouteWSService service = new XRouteWSService(url, qname);
XRouteWS client = service.getXRouteWSPort();
Map<String, Object> ctxt = ((BindingProvider)client).getRequestContext();
...
Map<String, List<String>> theHeaders = new HashMap<String, List<String>>();
theHeaders.put("Content-Encoding", Collections.singletonList("gzip"));
theHeaders.put("Accept-Encoding", Collections.singletonList("gzip"));
ctxt.put(MessageContext.HTTP_REQUEST_HEADERS, theHeaders);

Activating Fast InfoSet Encoding

For SOAP messages, PTV xServer 1.17 and newer support the FastInfoSet binary XML encoding. When compared with ordinary XML, this encoding is a little faster to process and leads to smaller messages. Fast Infoset encoding can be combined with http compression.

Up to date PTV Java client classes bundled with PTV xServer will use Fast Infoset by default. To deactivate fastinfoset on the java clients add this line before creating a new client.

System.setProperty("com.ptvag.xserver.client.fastinfoset.disabled", "true");

For JAX-WS, the mode can be activated with

ctxt.put("com.sun.xml.internal.ws.client.ContentNegotiation", "pessimistic");

PTV's .NET clients currently do not come with Fast Infoset support: .NET implementations for Fast Infoset do exist and work fine, but require an extra commercial license.

Authentication

In order to use HTTP authentication with an PTV xServer you have to create a file named users.properties in the conf/ folder of your PTV xServer installation. To add users and passwords add lines of the form userName=password to the file. The conf/users.properties will look somewhat like this:

default_user=<password>
admin_user=********
dev_user=********

HTTP authentication will be automatically turned on if the file "basic_root/conf/users.properties" exists. Detailed information considering HTTPS authentication is available in the PTV Customer Area (login needed).

You will have to restart the PTV xServer before the changes take effect.

Cross Origin Requests in Web Applications

To protect users from malicious scripts, browsers restrict Ajax requests to the URL protocol, domain and port the page originated from. This is called Same Origin Policy.

To host a web application using PTV xServer directly, there are several options to make cross origin requests work:

Send requests to the origin address of the web application and make the web server or a proxy redirect the PTV xServer queries to their appropriate destinations in the internal network. Most web servers / web application servers support such redirections (e.g. Apache's mod_rewrite or UrlRewriteFilter for Tomcat)
Bundle all PTV xServer modules into one domain and port (also known as the PTV xServer Bundle setup), and serve your web application from that location as well.
Use the CORS support in the PTV xServer Tomcat configuration. The servlet filter you need is already bundled and configured, so CORS will work out of the box. CORS usage is not supported by old browsers such as Internet Explorers before version 8, and has certain restrictions in Internet Explorer 8 and 9: most notably, custom http headers are not allowed.

There are further possible techniques, such as JSONP, or using window.postMessage from an iframe, but these approaches are more problematic regarding cross-site scripting attacks.