HTTP Requests

General information

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

Supported HTTP header fields

Direction Field Semantics
Request content-type Use application/soap+xml;charset=utf-8 for SOAPClosed SOAP (Simple Object Access Protocol) is a protocol specification for exchanging structured information in the context of Web services. XML is used for definition of the message format, and it is based on other application layer protocols, like Hypertext Transfer Protocol (HTTP) or Simple Mail Transfer Protocol (SMTP)., or application/json;charset=utf-8 for JSONClosed JSON (JavaScript Object Notation) is an open standard format for which human-readable text is used to transmit information consisting of attribute–value pairs. It is the first-address data format used for asynchronous browser/server communication (AJAX)..
username A user name to be checked against the mappings in For details see the User Authentication section of the server configuration.
password The password (in plain text) to be matched with the user.
accept-encoding: gzip

If the accept-encoding field contains the value 'gzip', the PTV xServer may send compressed responses, i.e. the response content is a gzip-Stream.

Features Features has two use cases:
x-tenant A PTV xServer can be shared by many different tenants. The server has to separate the data with the result that each tenant can access only to its own data. For example, the xDima service stores distance matrices of different tenants but each tenant has access to its own distance matrices only. This behaviour is described in Multitenancy and scopes.
xserver-module Assigns the request to a dedicated single PTV xServer backend instance. This feature is disabled by default. Set the configuration property to enable it.
Partner_Authentication A PTV xServer can be configured to accept requests from authorized partner applications only. This behaviour is described in Partner Authentication.
Response content-type Is returned as text/xml for SOAP (SOAP version is still 1.1), and application/json for JSON.
content-encoding: gzip This field contains the value 'gzip' if the server sends the response in compressed form.

HTTP response codes

PTV xServer does not support all existing HTTP status codes, the code ranges 1xx and 3xx are not considered at all.

Successful responses are returned with HTTP status code 200(OK).

Failed responses are roughly categorized into two different error classes: client errors and server errors. Client errors (HTTP status code 4xx) occur if the client sends an invalid request (HTTP status code 400 (Bad Request)), for example a request containing a typo in a field name, an incompatible value or fields of a newer version.
Access denied faults are treated differently and result in the HTTP status code 403 (Forbidden). They occur if a client does not have required admin access rights, for example for monitoring operations, or if the requested operation is forbidden by the Features header.

Server errors are thrown if the PTV xServer cannot decide definitely that the exception emerged from a client error. The HTTP status code is 500 (Internal Server Error) in this case.
Another special case is the QueueOverflowFault which is only thrown if there are too many requests in the xServer's request queue. It may therefore be reasonable to re-send the request automatically. For this reason the HTTP status code 503 (Service Unavailable) is returned.

Restrict unauthorized access for single service operations

Whitelist and blacklist

The restriction of a service operation must be specified on each request as a HTTP header named Features. Several features can be set as a comma separated list. For each service either a white- or a blacklist is allowed. A whitelist is a list of allowed operations. The Features string has the format (!)<ServiceName>.<OperationName>. The <ServiceName> could be a wildcard (*) for all services. The <OperationName> could contain a wildcard but it also must contain a part of the operation name. That means the string *.* is forbidden.

Here are some samples for the usage:

HTTP header Features Description
XRoute.* Allow all operations of XRoute.
XRoute.calculateRoute Allow only the operation calculateRoute of XRoute. All other operations of XRoute are forbidden.
!XRoute.start* All operations of XRoute starting with start are forbidden. The rest of the XRoute operations are allowed.
!XRoute.start*,XDima.createDistanceMatrix,XDima.start*,!XTour.* All operations of XRoute starting with start are forbidden. The rest of the XRoute operations are allowed. The operation createDistanceMatrix and all operations beginning with start of XDima are allowed. All other operations of XDima are forbidden. All operations of XTour are forbidden.
!*.start*,!*.fetch*,!*.*Job All asynchronous requests to all services are forbidden.

How to use the Features header in the RawRequestRunner

This is an example how to use the HTTP Header Features.

  1. Select a calculateRoute sample of the service XRoute in the RawRequestRunner.
  2. Click the icon "HTTP Header editor" above the request field and add Features:!XRoute.calculateRoute
  3. Execute the request.
    The response should be an AccessDeniedException with HTTP status code 403.