Versioning Guidelines

Introduction

The PTV xServer API and functionality is continuously extended. When updating to a new PTV xServer version, these changes can break client applications. To keep updating PTV xServer to latest version easy, a versioned API is provided. Each API version provides its own web service A web service represents a communication technology applied in computer networks. It provides an interface described in a machine-processable format, for example WSDL. end point:

head - http://localhost:50000/services/ws/XRoute
experimental - http://localhost:50000/services/ws/XRoute/experimental
2.0 - http://localhost:50000/services/ws/XRoute/2.0
2.1 - http://localhost:50000/services/ws/XRoute/2.1

API Versioning Types

There are different types of API versions, each is designed for a certain use case:

versioned

The versioned API provides a stable range of functions for productive usage. When updating to a new PTV xServer version, the server will downgrade the response objects to the requested version. While new PTV xServer versions might change the behavior for bug fixes and improvements, the syntax of the API will not change.

head

The head API is a reference to the latest versioned API of the PTV xServer. No type or operation of this API will be removed. Nevertheless updating PTV xServer to a new version, might bring API extensions like new types, new fields or new enumeration values. This API extensions can break typed web services clients. The error pattern strongly depends on the client technology. For weakly typed languages like JavaScript this API can be fine, as long as the client application handles unknown enumeration values and new type information like new exceptions properly.

experimental

The experimental API provides the latest PTV xServer API features. Every type or operation marked as experimental might be changed or even removed in future versions. Its purpose is to give customers the possibility to test new functionality as soon as possible.

Clients

Each PTV xServer ships with Java, C# and JavaScript clients for the experimental and current API. It is not recommended to use the Java and C# client with the head web service end point. Use the versioned web service end point instead.

Configuration

By default the PTV xServer configuration is shipped with the current version, the head and experimental API. Additional versions can be added at any time.

core {
    hostedVersions {
        default : [
            2.0,
            head,
            experimental
        ]
    }
}

Administrator's Guide	Services Configuration
Developer's Guide	Web Service Interface Principles