Web Service Interface Principles

SOAP and JSON over HTTP Post

PTV xServer web services support both SOAP and JSON messages. Both protocols are viable and both are 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 debatable anyhow: you can send data in JSON format with a plain http request and you will receive a response in JSON format - and that's that.

URL schema for web service end points

Web service end points follow a certain URL schema.

URL schema for SOAP:

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

URL schema for JSON:

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

JSON using HTTP Get

In addition to SOAP and JSON using HTTP Post methods there are also some xServer services that support methods using simple HTTP Get methods. Those RESTClosed REST (Representational State Transfer) represents a World Wide Web paradigm, consisting of constraints to the design of components which results in a better performance and maintainability.-like methods encode their parameters within the URL and return the response as JSON, binary data or text. The xmap service, for example, returns tile images on URLs specifying the requested zoom level and x- and y-tile indices.

URL schema

HTTP Get methods follow a certain URL schema:

http(s)://<hostname>:<port>/services/rest/<ServiceName>/<Version>/method/

Parameters follow the base schema and depend on the operation. Here's an example for xmap:

http(s)://<hostname>:<port>/services/rest/XMap/2.0/tile/{zoomLevel}/{x}/{y}?storedProfile={profileClosed A profile is a collection of parameters used to configure the request. Full profiles consist of a number of specialized sub-profiles like the VehicleProfile which describes the properties of a vehicle.}&contentType={contentType}&size={size}

Versioning

PTV xServer web services support versioning. This means that a URL with a specific version will still be accessible on a future version of the server. This allows easy updates without breaking existing applications. If you do not need the versioned API and always want to use the latest version, you can simply leave out the version from any URL. This Head version always points to the latest API:

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

HTTP Requests

Activating Message Compression

The PTV xServer will accept compressed requests and send compressed responses if the client has indicated acceptance by sending the appropriate headers. Clients generated from WSDL or by other means must explicitly activate 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 supports the Fast Infoset 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.

For JAX-WS, the mode can be activated with

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

Authentication

In order to use HTTP authentication with an PTV xServer you have to create a file: 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:

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

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 it originated from. This is called Same Origin Policy.

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

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.

Developer's Guide Versioning Guidelines