- 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
||A user name to
be checked against the mappings in
||The password (in plain text) to be matched with the user.|
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.
||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.|
||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.|
||A PTV xServer can be configured to accept requests from authorized partner applications only. This behaviour is described in Partner Authentication.|
||Is returned as text/xml for SOAP (SOAP version is still 1.1), and
||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
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
Request)), for example a request containing a typo in a field name, an incompatible value or fields of a newer
Access denied faults are treated differently and result in the HTTP status code
403 (Forbidden). They
client does not have required admin access rights, for example for monitoring operations, or if the requested operation is forbidden
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
(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
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.
Features string has the format
<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:
|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
- Select a calculateRoute sample of the service XRoute in the RawRequestRunner.
- Click the icon "HTTP Header editor" above the request field and add
- Execute the request.
The response should be an AccessDeniedException with HTTP status code 403.