Developer's Guide > Using the API documentation

Using the API Documentation

Each PTV xServer module comes with an API documentation that lists elements by kind.

Operations

Operations are grouped by web service (modelled as xService classes). For instance, the XMap service may define an operation renderMap. Operations may take parameters and return a result object or an exception.

For SOAP, the web service expects the so-called document/literal wrapped web service style. Each operation is represented by two complex types: one defining the request structure, and one defining the response structure. The operation is selected within the request. Names of parameters in SOAP request bodies do not match the ones in the documentation: They are enumerated using their type name and their position in the methods signature. If you create SOAP clients directly from the WSDL you will only see these names. The convenience Java and C#/.NET clients bundled with the PTV xServer are generated independently from the WSDL, and their parameters retain their original name.

For JSON, the services use a REST-like RPC style: each operation is represented by a unique end point (URL) and parameters are sent in one (anonymous) JSON request object. JSON objects include all names but few or no types.

Objects

Objects are structured and contain attributes with primitive values, enum values, or other objects.

Inside the WSDL you will find objects represented as complex types, and every array is represented with a wrapper element.

In JSON notation, objects are noted with curly brackets {}, and arrays are directly represented with square brackets []. The deserializer will interpret a left out (undefined) attribute as having the default value. Unless stated differently in the documentation, the default depends on the type: null, 0, or false. The order of the attributes is not relevant in JSON objects. In standard JSON, all attribute names have to be quoted, and an extra comma at the end of a list is not valid. White space outside strings is optional and should be left out for transmission; examples in this manual contain extra white space only for readability.

The primitive value types used within the API have straight-forward mappings to SOAP, JSON, and most programming languages. String, boolean, int, double are well-known. Boolean, Integer and Double are so-called boxed types which can be null as well. The type byte[] used for binary data is treated as a Base64-encoded String. The type Calendar is serialized as a String in the xsd:dateTime format, a subset of the ISO 8601 standard format.

Caution: Please make sure to always set all of the available properties to avoid errors based on misleadingly expected default values.

Enums

Enums are enumerations of legal values. The WSDL models enums as restricted strings. JSON also uses strings to represent enumeration values.

Exceptions

Exceptions define the error states that clients must deal with. There are typically three kinds of exception thrown by xServices:

SOAP represents exceptions as SOAP Faults. The sub-elements faultcode and faultstring contain the error key and the original error message. The detail element contains the original exception object in xml notation, which is used by the Java and C# clients to deserialize the exception. In JSON mode, exceptions are returned as anonymous JSON objects with the following attributes:

Attribute Name Description
errorMessage The original error message
errorKey The error key
exceptionType The exception type, e.g. Service Exception, xService Exception or JsonParseException
errorLine In case of a JsonParseException this attribute holds the line number where the error occurred
errorColumn In case of a JsonParseException this attribute holds the column number where the error occurred

Polymorphic Types in JSON

In contrast to SOAP where object properties are typed but are not named, objects in JSON are named but not typed. This brings a challenge for the polymorphic types that are part of the PTV xServer API.

In many cases, the type is obvious to the human eye, since instances of inherited types often have unique attributes that identify them unambiguously. Assigning a type according to observed names or values is called duck typing: If it looks like a duck, swims like a duck, and quacks like a duck, then it probably is a duck. Unfortunately, duck typing only works for cases when objects of different types do differ in attributes, and this is not always guaranteed in the current PTV xServer API.

Thus, the JSON web service falls back to type hinting. In all places where a polymorphic type is expected, there has to be a specially named property $type, providing the (unqualified) type name. We abstained from mixing type hinting and duck typing to avoid confusion and the necessity to write a type deserializer from scratch: currently, JSON frameworks do not handle duck typing well.

Type hints are only mandatory to indicate a subtype of the expected type for an attribute. If the concrete type matches the expected type (and is either a leaf type of the type hierarchy or a concrete base type), the type hint can be omitted. The following example shows a TourPointDesc that tells the service that it is not a mere WaypointDesc. A WaypointDesc would not need a type annotation.

{
  "$type": "TourPointDesc",
  "coords": [
  { "point": { "x": 676437, "y": 6448604 } }
  ],
  "linkType": "NEXT_SEGMENT",
  "completeServiceInIntervals": true,
  "servicePeriod": 100,
  "useServicePeriodForRecreation": false
}

CallerContext

The CallerContext is a set of properties that can be set for each request as an additional argument after the business parameters, similar to the RequestOptions object as defined in the common package.

Attribute Name Type Description
properties Key-Value list with keys and values from RequestOptions The request options to be used for this request.
log1, log2, log3 String Optional log strings that will be passed directly to the logging infrastructure, so that client requests may be aggregated by category name in the logs.

There are a few noteworthy specialities:

Example for a code snippet of a SOAP request with the caller context element:

<callerContext_5 log1="company name" log2="sector" log3="">
 <wrappedProperties xmlns="http://baseservices.service.jabba.ptvag.com">
  <CallerContextProperty key="CoordFormat" value="PTV_MERCATOR" />
  <CallerContextProperty key="ResponseGeometry" value="PLAIN"/>
  <CallerContextProperty key="Profile" value="default" />
 </wrappedProperties>
</CallerContext_5>

Example for the Java client code corresponding to this SOAP request:

XLocateRemoteInterface xLocateClient =
(XLocateRemoteInterface)ClientFactory.createClient(XLocateRemoteInterface.class,
  RemoteType.DOCSTYLE_CXF,"","",url);
CallerContext ctx = new CallerContext();
ctx.setLog1("company name");
ctx.setLog2("sector");
CallerContextProperty ctxprop1 = new CallerContextProperty();
ctxprop1.setKey("CoordFormat");
ctxprop1.setValue("PTV_MERCATOR");
CallerContextProperty ctxprop2 = new CallerContextProperty();
ctxprop2.setKey("ResponseGeometry");
ctxprop2.setValue(GeometryEncoding.PLAIN.getValue());
CallerContextProperty ctxprop3 = new CallerContextProperty();
ctxprop3.setKey("Profile");
ctxprop3.setValue("default");
CallerContextProperty[] prop = { ctxprop1, ctxprop2, ctxprop3 };
ctx.setProperties(prop);
xLocateClient.setCallerContext(ctx);

Deprecated Elements

Entities marked as deprecated will be removed with the next major release (2.0, 3.0, ...).

There are functional alternatives available you can use instead. You should not use deprecated operations or options when you write new code.

Deprecated operations or options will not be extended but will still receive bug fixes and are still supported.

 

 

Copyright © 2024 PTV Logistics GmbH All rights reserved. | Imprint