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 RESTREST (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={profileA 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

• PTV xServer services are accessed with HTTP Requests using the POST or GET method.
• There are some useful standard and custom HTTP request and response header fields that influence PTV xServer behavior or provide extra meta information.
• For details see the section about 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:

• 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 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:

• 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 services 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.

Related Topics