Skip to content

C. Protocol Version Compatibility

This chapter documents some of the major caveats between AlpineBits® clients and servers. The provided list of incompatibilities is not meant to be exhaustive and it is highly encouraged that partners use the same version of AlpineBits® for exchanging data whenever possible. Most notably a client is highly discouraged from using different AlpineBits® versions for different actions when interacting with the same server.

C.1. Major overhaul in version 2022-10

GuestRequests

The SpecialRequests attribute Name has been replaced with RequestCode and a new CodeContext attribute has been added.

The special case which allowed to specify alternative periods by adding one optional RoomStay element with only one TimeSpan element has been removed in favor of the new RoomStayGroupID attribute.

FreeRooms

In version 2022-10 a server might not handle CompleSet messages for OTA_HotelInvCountNotif:FreeRooms but it MUST provide the capability OTA_HotelInvCountNotif_accept_complete_set if it does.

C.2. Major overhaul in version 2020-10

Currency

The version 2020-10 adds support for all currency codes from the ISO 4217 in all actions where amounts are used.

Guidelines to exchange copyright and license information on multimedia objects like images have been added to the chapter data exchange.

GuestRequests

The version 2020-10 introduces some new options:

  • special requests regarding pets (SpecialRequests)

  • RoomType attribute now is mandatory only for reservations

FreeRooms

In version 2020-10 the FreeRooms message has been changed from OTA_HotelAvailNotif to OTA_HotelInvCountNotif. The chapter has been completely re-written and OTA_HotelAvailNotif is to be considered deprecated. Even all relative capabilities and action names have been changed.

OTA_HotelAvailNotif (old) OTA_HotelInvCountNotif (new)

action_OTA_HotelAvailNotif

action_OTA_HotelInvCountNotif

OTA_HotelAvailNotif_accept_rooms

OTA_HotelInvCountNotif_accept_rooms

OTA_HotelAvailNotif_accept_categories

OTA_HotelInvCountNotif_accept_categories

OTA_HotelAvailNotif_accept_deltas

OTA_HotelInvCountNotif_accept_deltas

OTA_HotelAvailNotif_accept_BookingThreshold

OTA_HotelInvCountNotif_accept_out_of_market

-

OTA_HotelInvCountNotif_accept_out_of_order

-

OTA_HotelInvCountNotif_accept_closing_seasons

The new message offers the same options as the one used previously, but introduces the following new options:

  • sending of closing seasons

  • rooms out-of-order OTA_HotelInvCountNotif_accept_out_of_order

RatePlans

A new mandatory attribute CurrencyCode of the RatePlan element has been introduced to support all ISO 4217 currency codes.

Inventory/HotelInfo

The specification of Inventory/Hotelinfo has been expanded and provides an explicit structure for the exchange of hotel information. The version 2020-10 now defines the acceptable structure of HotelDescriptiveContent and its sub-elements. This action is no longer considered experimental.

Activities

This new action has been introduced with 2020-10. It is used to exchange information about hotel internal activities.

C.3. Major overhaul in version 2018-10

Housekeeping / Handshaking

The Housekeeping action has been renamed to Handshaking and the relative chapter has been completely rewritten introducing breaking changes. Through the introduction of the OTA_Ping:Handshaking action it is now possible for clients to expose the capabilities they support.

New action GuestRequests (Push)

This functionality was introduced in version 2018-10.

It is now possible to push GuestRequests instead of polling them. Please note that this functionality relies on a few arrangements between the two parties that are not negotiated through AlpineBits®, namely the endpoint (URL) where the client can receive the pushed GuestRequests, its credentials, etc.

New attribute RoomType

This functionality was introduced in version 2018-10.

For Inventory and GuestRequests, in addition to the RoomClassificationCode attribute, the optional attribute RoomType has been added in order to allow a more precise classification of the guest accommodation.

Reference to the online presence of the lodging structure

This functionality was introduced in version 2018-10.

For Inventory, the element ContactInfos can be used to transmit URIs where the lodging structure has a presence (like social networks, review aggregators, etc.).

Review price calculation

These changes were made to the price calculation algorithm:

  • The AdditionalGuestAmount element with attribute AgeQualifyingCode equal to 10 becomes optional.

  • The AdditionalGuestAmounts element can be transmitted also if the MaxOccupancy attribute is equal to the StandardOccupancy.

Interaction with channel managers

  • For BaseRates, a new case is described that allows servers to exchange information with clients that are only able to send RatePlans overlay information.

  • For GuestRequests of type Reservation, a recommendation to set the value of the mandatory RatePlanCode attribute to the string "Unknown" has been added to ease the integration with channel managers that do not provide a reference to the AlpineBits® RatePlan which the GuestRequest actually refers to.

Server request for complete data set

In case of a suspected misalignment of data, servers can now request the client to send a full data set.

RatePlans

Version 2018-10 introduced optional [xml_element_name]AdditionalGuestAmount# elements. Since they were mandatory in version 2017-10, a communication between both versions is only possible if the request from 2018-10 is gapless.

C.4. Major overhaul in version 2017-10

AlpineBits® server response outcomes

The AlpineBits® response outcomes (success, advisory, warning, error) are now uniformly and more thoroughly defined in the new appendix A.

In particular the distinction between warning and error outcomes is more in line with the OTA documentation 3 (see the section "OpenTravel Message Success, Warnings & Errors Elements").

Implementations of 2015-07b will likely signal as errors, things that in 2017-10 would be considered warnings. This should not lead to breakage, however, since both (warnings and errors) unambiguously indicate failed requests and this has been spelled out with greater clarity in the 2017-10 document.

In any case implementors are invited to have a close look at the new appendix A.

FreeRooms

Two new features have been added to FreeRooms: transmission of the number of bookable rooms and purge requests.

GuestRequests

Two new features have been added to GuestRequests: commissions and encrypted credit card numbers. The credit card holder name was made optional. Some info on how to fill out the ReservationID was added to the best practice section.

SimplePackages

The feature has been removed in version 2017-10.

Inventory

Inventory messages were introduced in version 2014-04 and overhauled in version 2015-07.

In version 2017-10 the section was again changed significantly. The former Inventory request action has been heavily refactored and split into four different actions:

  1. Inventory/Basic: (push) action OTA_HotelDescriptiveContentNotif:Inventory (same string was also used in previous version) is now only used to send room category information and room lists (unlike previous versions, where it had multiple uses).

  2. Inventory/Basic (pull): action OTA_HotelDescriptiveInfo:Inventory (new) is used to request basic information.

  3. Inventory/HotelInfo (push): action OTA_HotelDescriptiveContentNotif:Info (new) is used to send additional descriptive content.

  4. Inventory/HotelInfo (pull): action OTA_HotelDescriptiveInfo:Info (new) is used to request additional descriptive content.

Of course the corresponding action capabilities have been defined.

Due to the split, these capabilities are no longer necessary and were removed:

  • OTA_HotelDescriptiveContentNotif_Inventory_accept_basic

  • OTA_HotelDescriptiveContentNotif_Inventory_accept_additional

RatePlans

Concerning booking rules, previously the attribute MinMaxMessageType of LengthOfStay could assume the two values SetMinLOS and SetMaxLOS and there were two corresponding capabilities (OTA_HotelRatePlanNotif_accept_MinLOS and OTA_HotelRatePlanNotif_accept_MaxLOS). With 2017-10 the list of values have been expanded to four by adding SetForwardMinStay and SetForwardMaxStay. As all four values must be supported the two capabilities have been removed.

It is now possible to define supplements that are only available on given days of the week and supplements that depend on room category.

Offers have been improved and extended: besides the discounts, the Offer element is now also used to transmit the age above which a guest is considered an adult and a number of restrictions (for which 2 new capabilities (starting with OTA_HotelRatePlanNotif_accept_OfferRule) have been introduced). Free night discounts have also been slightly updated.

Changes have been made to the algorithm describing the computation of the cost of a stay (see section 4.5.2): there is now a new step 1b, step 3 has been changed (a rate plan is now applicable even if it has a family offer that doesn’t match the stat) and step 4b has been simplified (as we have complete and gapless age brackets for all possible child ages now).

Descriptions have been extended and documented more thoroughly.

BaseRates

This action has been introduced with 2017-10.

C.5. Minor updates in version 2015-07b

Version 2015-07b is a maintenance release. The section 4.5 about rate plans has been mostly rewritten with more precise and strict information about how to handle corner cases, especially regarding rebates.

While most of this does not lead to breaking changes per se, it is likely that 2015-07 servers that were implemented before the release of 2015-07b would compute costs for stays differently, for lack of a sufficiently strict description of details.

One deliberate breaking change of note is that 2015-07b requests the value of the AmountAfterTax attribute in BaseByGuestAmt elements to be > 0, while 2015-07 used to allow a value ≥ 0.

C.6. Major overhaul in version 2015-07

Inventory

In version 2015-07 the Inventory message was changed from OTA_HotelInvNotif to OTA_HotelDescriptiveContentNotif. The new message offers the same options as the one used previously beside sending the name of the specific rooms, but allows for much richer descriptions, including pictures. A high-level mapping between the old Inventory and the new one is as follows:

OTA_HotelInvNotif OTA_HotelDescriptiveContentNotif

SellableProduct

GuestRoom

SellableProduct InvTypeCode

GuestRoom Code

SellableProduct InvCode

TypeRoom RoomID

Quantities MaximumAdditionalGuests

Not needed anymore, see StandardOccupancy

Occupancy MinOccupancy

GuestRoom MinOccupancy

Occupancy MaxOccupancy

GuestRoom MaxOccupancy

Occupancy AgeQualifyingCode="8"

GuestRoom MaxChildOccupancy

Not previously possible

TypeRoom StandardOccupancy

Room RoomClassificationCode

TypeRoom RoomClassificationCode

Amenity AmenityCode

Amenity RoomAmenityCode

Text

TextItem > Description

Not previously possible

ImageItem > URL

Text (for specific Room)

Not possible anymore

C.7. Major overhaul in version 2014-04

Version 2014-04 was a major overhaul. In most cases, a pre-2014-04 client will not be compatible with a 2014-04 server and viceversa. Here is a list of major changes in 2014-04.

HTTPS layer

The possibility of compression with gzip has been added.

FreeRooms

The possibility to send booking restrictions in FreeRooms has been removed as have the corresponding capabilities. These are better handled by the new RatePlans.

The value of the action parameter has been changed from FreeRooms to OTA_HotelAvailNotif:FreeRooms for uniformity with the other action values that all follow the rootElement:actionValue format.

The possible responses (OTA_HotelAvailNotifRS document) have been re-categorized into four classes: success, advisory (new), warning and error. For error responses the attributes have changed, fixing a bad OTA interpretation.

Finally, the way deltas and complete transmissions are distinguished has changed. All in all FreeRooms are not compatible with any previous version.

GuestRequests

GuestRequests have been heavily refactored. Previous AlpineBits® versions had two type of requests: quotes and booking requests, the current version has three: booking reservations, quote requests and booking cancellations. Also, the client can (and must) now send acknowledgements.

SimplePackages

The possible responses (OTA_HotelRatePlanNotifRS document) have been re-categorized into four classes: success, advisory (new), warning and error. For error responses the attributes have changed, fixing a bad OTA interpretation.

Inventory and RatePlans

These are new message types introduced with version 2014-04.

C.8. Compatibility between a 2012-05b client and a 2013-04 server

Housekeeping

The client will not send the X-AlpineBits-ClientID field in the HTTP header, since it is not aware of this feature. This will cause authentication problems with those 2013-04 servers that require an ID.

The client will not send the X-AlpineBits-ClientProtocolVersion field in the HTTP header, since it is not aware of this feature. This is no problem: a server that is interested in this, will simply recognize the client as preceding protocol version 2013-04.

If the client checks the server version it will see 2013-04 - a version it doesn’t recognize. Likewise, if the client checks the capabilities it might see the OTA_HotelAvailNotif_accept_deltas capability. Client implementers interested to have their 2012-05b client talk to a 2013-04 server should verify this is not a problem for their client software.

FreeRooms

There is no compatibility problem in the request part: the client will not send partial information (deltas), since it is simply not aware of the existence of the feature. Please be aware that the lack of this feature (obviously) causes more data to be sent to the server, something not all companies that run servers will be happy with. The server response might contain a Warning element the client cannot process. If the client - as it should - carefully parses the response, it will treat this as an error situation and act accordingly. So basically the client is expected to treat the warnings as error, which might be an issue and this should be tested.

GuestRequests

No compatibility problems are expected.

SimplePackages

2013-04 introduced the limitation that all packages sent within a single request must refer to the same hotel. An older client not aware of this limit might incur an error returned from the server error.

Similar to the FreeRooms case, the server response might contain a Warning element the client cannot process. If the client - as it should - carefully parses the response, it will treat this as an error situation and act accordingly. So basically the client is expected to treat the warnings as an error, which might be an issue and should be tested for.

C.9. Compatibility between a 2013-04 client and a 2012-05b server

Housekeeping

The client sends the X-AlpineBits-ClientProtocolVersion field and may send the X-AlpineBits-ClientID field in the HTTP header, but the server will just ignore it - being unaware of the feature. If the client checks the server version and/or checks the capabilities - as it should - it will note the missing features and not use them. Hence, technically there is no problem with this combination.

FreeRooms

The client will not send partial information (deltas), since the server does not export the OTA_HotelAvailNotif_accept_deltas capability.

The server will never send a response with a Warning element. This is not a problem for the client.

GuestRequests

In 2013-04 the form of the ID attribute is not any more restricted. It has become a free text field. An older server might insist on the old form and throw an error.

SimplePackages

The server will never send a response with a Warning element. This is not a problem for the client.