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 SOAP 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 JSON 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 `users.properties`. 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: Use `!adminAccess` to forbid the access to administration pages / monitoring for IPs that are listed in the admin access whitelist A whitelist is a list of host names, IP addresses or IP ranges which are allowed access or to be accessed. All other hosts do not have access.. The default behavior is unrestricted access. This means all http requests to the PTV xServer are allowed. All requests to the dashboard including the administration pages like Status Monitor are allowed. Restrict unauthorized access for single service operations.
	`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 core.security.moduleSpecificMonitoringRequests 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).

SOAP 1.1 does only support the response codes 200 (OK) and 500 (Internal Server Error). Therefore the following paragraph only accounts for JSON and REST

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

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

Customers can use PTV xServer as a backend server for their own applications. It can be useful to control the access of separate service operations by each request. For example if an application has users with different licenses and thereby different rights. Operations can be explicitly forbidden for each user.

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.

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