Understanding Universal API Web Services and Schema

The Universal API services are document-style SOAP Web Services. The download package includes both schema (*.xsd) and Web Services definition language (*.wsdl) files that are organized around a set of services. All schema files import an additional schema file, Common.xsd, which contains schema elements and attributes that are used throughout the schema files of the Universal API services.

For each service, there are two WSDL files:

• The abstract file (e.g., AirAbstract.wsdl), imported by the non-abstract file (e.g., Air.wsdl), describes the messages and port types.
• The non-abstract version describes the binding and the service.

Each schema file contains requests for a specific service, some shared objects, and the Common.xsd file. For example:

• AirReqRsp.xsd contains all the requests necessary to search for flights, and create and ticket a reservation.

• UniversalRecordReqRsp.xsd contains requests to work with Universal Records (URs) that have been created or ticketed.

Whenever possible, schema and processing have been normalized in Universal API.

Using SOAP

Universal API uses SOAP to handle requests and responses. SOAP is one of the most common protocols for Web Services, as SOAP is supported by the majority of programming languages (Java, C#, .NET, and PHP).

Using the schema files, most programming languages can create proxy classes that allow easy creation of requests and parsing of responses. These proxy classes typically also handle the SOAP protocol for you, as long as you provide credentials and the correct endpoint.

While the transactions might appear “heavier” than a similar transaction using JSON, the use of GZIP compression ensures the actual data transmitted is small. Responses are compressed automatically by the Universal API server when you set the header Accept-Encoding to gzip.

The Programming Model

Universal API uses a design that exposes a port which has a single method called service, regardless of programming language. Many programming languages use the terminology "method” or “function call” when referring to sending a request over the network via the given port.

The documentation for Universal API refers to the port object by its name, so rather than “the ping port”, it is just “ping”. In most programming languages, all the ports exposed from the file System.wsdl start with System and end with PortTypewhen they are generated from this WSDL.

Every request that is sent must also contain your credentials in the HTTP Header. These are the credentials Travelport provided when you signed up to use Universal API.

It is good practice to turn on “full validation” when developing your application, no matter the programming language you are using. This means that your system will not attempt to transmit XML sequences that are invalid, and thus likely to be rejected.

Generating Client-Side Code

Almost any programming language can be used to work with Universal API. In practice, coding is easiest with a generator, such as Apache Axis or Apache CXF, that can take a file “file.wsdl” and spit out “file_client.Java” in your favorite language.

Note: Different generators have slightly different behaviors.

It is recommended that you generate the client-side code for the services you plan to use. Air, Hotel, and Vehicle services are the most commonly used and are often used in conjunction with each other.

Versioning and Backwards Compatibility

Each service (Universal Record, Air, Vehicle, Hotel, Common, etc.) is managed separately for each release. Versions are identified by major/minor/patch in the namespace of the service definition (WSDL).

• Major versions are incremented due to architectural changes.
• Minor changes are incremented due to service enhancements.
• Patch changes occurs after a service is delivered.

A file of the differences between one version and the next can be downloaded on the Downloading WSDLs and Schemas page.

Universal API versions are supported for three years, and when Travelport plans to retire a version, customers using that version will be notified. Please note that new functionality most likely is not available in older versions.

If elements or attributes in a new version are supported in prior versions, the Developer Advisory and the online help will note the backwards compatibility.

Design and Use

The following factors were considered when designing Universal API services and schema.

Reusability

When designing the schema, we chose to promote reusability of elements rather then creating multiple versions. So, in different contexts, many elements will have different required attributes and/or child elements. As a result, the definition must be loose enough (not required) to handle all scenarios. For example, AirPricingSolution uses shared elements in search responses and defined elements in AirCreateReservationReq. So, although the definition states that almost all elements and attributes are optional, in actual usage, specific elements are required to perform a specific business process.

Shared Elements

Due to the shared element concept used in search responses, many elements have a companion Ref element. For example, AirSegment and AirSegmentRef. One of these elements must always accompany an AirPricingSolution, but which element is used depends on the context. AirSegmentRef is used when searching, and AirSegment is used when creating a reservation.

XML Retention

We also made the assumption, and try to encourage, that client applications would retain and pass back the original AirPricingSolution that was returned during search. If the solution was passed back in without modification to AirCreateReservationReq, the only modification would be to merge the shared elements. This method is how pricing data is handled throughout the system.

Design Approach

Given the above decisions and assumptions, it is apparent that it is not always desirable or feasible to retain complex AirPricingSolution data, even though most providers and suppliers house similar data.

However, because Universal API does not store data in a work area (or AAA) where segment data can be held and ignored while pricing is being attained, the approach must be modified. As a result, we have made it possible for much of the data to be omitted, and for Universal API to determine the appropriate missing data.

This design approach is put into practice when it is feasible to accommodate the minimum requirements of a transaction. In actual use, this approach is sometimes modified when the complexity of the data requires more details.

For example, an AirSegment element has many attributes and child elements, but AirSegment can be defined with only seven pieces of data: Origin, Destination, Departure date/time, Arrival date/time, Carrier, Flight Number, Class of Service. Although this data properly defines the entity to be booked, it still lacks much contextual information that must be known to properly sell and ticket the resulting PNR. Therefore, additional elements, such as Group and MarriageGroup, are needed for to fully determine the Origin and Destination pairs, and whether or not these pairs are married.