3. Handshaking action¶

The handshaking action allows client and server to agree on the supported AlpineBits® versions and capabilities. Any AlpineBits® client or server must be able to handle this request. In the rest of this chapter the word "actor" will be used when referring to either client or server.

It is the client’s responsibility to ensure the server can handle the actions it intends to perform. The client should update capabilities periodically. The server may request an update of the capabilities from the client by sending a response described in Appendix A under paragraph "Responses with a request for complete sets of data"

Please note that this chapter was completely rewritten in AlpineBits® 2018-10 version, and it introduces breaking changes. This was needed to significantly streamline the handshaking progress.

The following table lists all available handshaking actions.

usage (since)	mandatory	parameter `action` (string)	parameter `request` and server response (XML document) [small]
client sends its supported actions and capabilities (since 2018-10)	YES	`OTA_Ping:Handshaking`	OTA_PingRQ OTA_PingRS

3.1. Client request¶

The parameter request must contain an OTA_PingRQ document.

The EchoData element must contain a JSON object, and adhere to the following rules:

The root element is a JSON array with name versions.
Each element of the array versions is a JSON object.

Each object of the versions array is built according to the following rules:

A member with name version and value corresponding to a valid AlpineBits® version string must be present (see the first column of the changelog table, e.g. 2018-10 for the first version of AlpineBits® that supports handshaking)
A JSON array with name actions may be present.

Each element of the actions array is a JSON object built according to the following rules:

A member with the name action and value corresponding to one supported action.
A JSON array with name supports, listing all the supported capabilities for the sibling action.

In general the client should always start handshakes with the highest version he supports. If the client doesn’t receive a positive response from the server, the client should try to reconnect by decreasing to the next lower version he supports. If there is no common version, no communication is possible. For more details on server responses in the handshake see section 3.2.

<EchoData> { "versions": [{ "version": "2018-10", "actions": [ { "action": "action_OTA_Ping" },{ "action": "action_OTA_HotelRatePlan_BaseRates", "supports": ["OTA_HotelRatePlan_BaseRates_deltas"] },{ "action": "action_OTA_HotelRatePlanNotif_RatePlans", "supports": [ "OTA_HotelRatePlanNotif_accept_overlay", "OTA_HotelRatePlanNotif_accept_Supplements", "OTA_HotelRatePlanNotif_accept_RatePlan_BookingRule", "OTA_HotelRatePlanNotif_accept_FreeNightsOffers", "OTA_HotelRatePlanNotif_accept_FamilyOffers" ] } ] }] } </EchoData>

example of Handshake client request, only the EchoData element is shown.

For every succesfully negotiated (see below) action, the client must set the X-AlpineBits-ClientProtocolVersion HTTP header according to the sibling version when performing the subsequent data exchange with the server.

In order to avoid misintepretations, the AlpineBits® versions below 2018-10 may be part of the JSON object, but there must not be any actions array specified for them. The handshaking of the legacy versions must happen in subsequent requests following the legacy rules.

3.2. Server Response¶

The response is an OTA_PingRS document.

As mandated by OTA, the content of the EchoData element must be identical to what the client sent.

The server must add to the response a Warning element with Type 11 and Status ALPINEBITS_HANDSHAKE. The content of this element must be the intersection between the client announced versions, actions and capabilities and what the server actually supports.

If a server receives a handshake request with a version he doesn’t support or doesn’t know, the server is allowed to reject the message with an error and a textual description about version incompatibility. This error is thrown by only checking the X-AlpineBits-ClientProtocolVersion.

For better compatibility the server may not directly reject the connection based on the header information, but trying to fulfill the handshake by checking if he supports one of the versions indicated by the client. The answer would be an intersection of common versions in order to give a more specific answer to the client. In that case compatibility between client and server is found within the handshake on the first connection.

In any case this is also valid for the OTA_Ping. If the server supports the version, but no intersection other than OTA_Ping is found, a server should answer to be exclusively compatible with OTA_Ping. This implies there are no common actions between client and server. Otherwise the server should not reply supporting this version at all.

<?xml version="1.0" encoding="UTF-8"?> <OTA_PingRS xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.opentravel.org/OTA/2003/05" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 OTA_PingRS.xsd" Version="8.000"> <Success/> <Warnings> <Warning Type="11" Status="ALPINEBITS_HANDSHAKE"> { "versions": [{ "version": "2018-10", "actions": [ { "action": "action_OTA_Ping" },{ "action": "action_OTA_HotelRatePlan_BaseRates", "supports": ["OTA_HotelRatePlan_BaseRates_deltas"] } ] }] } </Warning> </Warnings> <EchoData> { "versions": [{ "version": "2018-10", "actions": [ { "action": "action_OTA_Ping" },{ "action": "action_OTA_HotelRatePlan_BaseRates", "supports": ["OTA_HotelRatePlan_BaseRates_deltas"] },{ "action": "action_OTA_HotelRatePlanNotif_RatePlans", "supports": [ "OTA_HotelRatePlanNotif_accept_overlay", "OTA_HotelRatePlanNotif_accept_Supplements", "OTA_HotelRatePlanNotif_accept_RatePlan_BookingRule", "OTA_HotelRatePlanNotif_accept_FreeNightsOffers", "OTA_HotelRatePlanNotif_accept_FamilyOffers" ] } ] }] } </EchoData> </OTA_PingRS>

example of Handshake server response.

3.3. List of AlpineBits® supported `actions` and `capabilities`¶

action_OTA_Ping
handshaking action (support for this action is mandatory)
action_OTA_HotelInvCountNotif
the actor implements handling room availability notifications (FreeRooms)
OTA_HotelInvCountNotif_accept_rooms
for room availability notifications (FreeRooms), the actor handles availabilities for specific rooms
OTA_HotelInvCountNotif_accept_categories
for room availability notifications (FreeRooms), the actor handles availabilities for room categories
OTA_HotelInvCountNotif_accept_complete_set
for room availability notifications (FreeRooms), the actor handles CompletSet messages
OTA_HotelInvCountNotif_accept_deltas
for room availability notifications (FreeRooms), the actor handles partial information (deltas)
OTA_HotelInvCountNotif_accept_out_of_order
for room availability notifications (FreeRooms), the actor handles the number of rooms that are considered out of order
OTA_HotelInvCountNotif_accept_out_of_market
for room availability notifications (FreeRooms), the actor handles the number of rooms that are considered free but not bookable
OTA_HotelInvCountNotif_accept_closing_seasons
for room availability notifications (FreeRooms), the actor handles closing seasons
action_OTA_Read
the actor implements handling quote requests, booking reservations and cancellations (GuestRequests Pull)
action_OTA_HotelResNotif_GuestRequests
the actor implements pushing quote requests, booking reservations and cancellations (GuestRequests Push)
action_OTA_HotelResNotif_GuestRequests_StatusUpdate
the actor implements the status update for quote requests (GuestRequests Push status update)
action_OTA_HotelDescriptiveContentNotif_Inventory
the actor implements handling Inventory/Basic (push)
OTA_HotelDescriptiveContentNotif_Inventory_use_rooms
for room category information (Inventory), the actor needs information about specific rooms
OTA_HotelDescriptiveContentNotif_Inventory_occupancy_children
for room category information (Inventory), the actor supports applying children rebates also for children below the standard occupation
action_OTA_HotelDescriptiveContentNotif_Info
the actor implements handling Inventory/HotelInfo (push)
action_OTA_HotelDescriptiveInfo_Inventory
the actor implements handling Inventory/Basic (pull)
action_OTA_HotelDescriptiveInfo_Info
the actor implements handling Inventory/HotelInfo (pull)
action_OTA_HotelRatePlanNotif_RatePlans
the actor implements handling prices (RatePlans)
OTA_HotelRatePlanNotif_accept_ArrivalDOW
for prices (RatePlans), the actor accepts arrival DOW restrictions in booking rules
OTA_HotelRatePlanNotif_accept_DepartureDOW
for prices (RatePlans), the actor accepts departure DOW restrictions in booking rules
OTA_HotelRatePlanNotif_accept_RatePlan_BookingRule
for prices (RatePlans), the actor accepts "generic" booking rules
OTA_HotelRatePlanNotif_accept_RatePlan_RoomType_BookingRule
for prices (RatePlans), the actor accepts "specific" booking rules for the given room types
OTA_HotelRatePlanNotif_accept_RatePlan_mixed_BookingRule
for prices (RatePlans) and within the same rate plan, the actor accepts both "specific" and "generic" booking rules. Both "generic" and "specific" rules capabilities must still be announced by the actor.
OTA_HotelRatePlanNotif_accept_Supplements
for prices (RatePlans), the actor accepts supplements
OTA_HotelRatePlanNotif_accept_FreeNightsOffers
for prices (RatePlans), the actor accepts free nights offers
OTA_HotelRatePlanNotif_accept_FamilyOffers
for prices (RatePlans), the actor accepts family offers
OTA_HotelRatePlanNotif_accept_overlay
for prices (RatePlans), the actor accepts the rate plan notif type value Overlay
OTA_HotelRatePlanNotif_accept_RatePlanJoin
for prices (RatePlans), the actor supports grouping RatePlans with different MealPlanCodes under a single price list
OTA_HotelRatePlanNotif_accept_OfferRule_BookingOffset
for prices (RatePlans), the actor accepts the OfferRule restrictions MinAdvancedBookingOffset and MaxAdvancedBookingOffset
OTA_HotelRatePlanNotif_accept_OfferRule_DOWLOS
for prices (RatePlans), the actor accepts the OfferRule restrictions ArrivalDaysOfWeek, DepartureDaysOfWeek, SetMinLOS and SetMaxLOS
action_OTA_HotelRatePlan_BaseRates
the actor implements handling BaseRates
OTA_HotelRatePlan_BaseRates_deltas
the actor supports delta information with BaseRates
action_OTA_HotelPostEventNotif_EventReports
the actor implements handling hotel internal activities

AlpineBits® requires an actor to support at least all mandatory handshaking actions.

All other capabilities are optional. It is a client’s responsibility to check for server capabilities before trying to use them. A server implementation is free to ignore information that requires a capability it doesn’t declare. A server must, however, implement all capabilities it declares.

3.4. Unknown or missing actions¶

Upon receiving a request with an unknown or missing value for action, the server response is the string: ERROR:unknown or missing action.

Please note that the legacy "housekeeping actions" (namely: getVersion and getCapabilities) have been removed from this version of AlpineBits® and will yield to such a response.

3.5. Implementation tips and best practice¶

OTA requires the root element of an XML document to have a version attribute. In regards to AlpineBits®, the value of this attribute is irrelevant.
The handshaking action allows actors that are able to support multiple AlpineBits® versions to negotiate the best combinations of versions and capabilities with a single request. The suggested approach for a client is to list all the AlpineBits® versions and the related actions / capabilities it supports in a single request.
Since the server is performing an intersection between the received JSON object and its supported versions and capabilities the response might be an empty JSON object ({}), this is an indication that there was a failure in parsing the JSON of the request.
When a client upgrades its AlpineBits® version, it is advised for it to re-configure all connections with its partner servers (provided they support the new version) starting from the handshaking and dealing with each data exchange action as a first synchronization in order to overwrite servers' data. This is to avoid any ambiguity or data-loss due to possible breaking changes between the old and new version. Examples of such breaking changes could be found when upgrading to version 2017-10 (or higher) with the introduction of static rates or when upgrading to version 2020-10 (or higher) with the re-writing of the FreeRooms action introducing the new out-of-order categories. In case a server receives a delta message with an AlpineBits® version which is inconsistent with the previously stored data, a server is free to decide whether to alert the client by sending a warning, to delete the stored data and/or to request a full re-synchronisation from the client (complete set).
A server may inform the client regarding the deprecation of the current request through the headers Deprecation and Link, as defined by the IETF (https://datatracker.ietf.org/doc/draft-ietf-httpapi-deprecation-header). These headers may be added to the response of any type of action that the server deems appropriate to deprecate, and applies to that specific action.

For the complete explanation of the headers, their syntax and use cases, please refer to the source linked above. As example, one endpoint serving an obsolete version of AlpineBits could be returning the following headers:
```
Deprecation: Mon, 19 Oct 2020 23:59:59 GMT
Link: <\https://developer.alpinebits.org/deprecation.txt>; rel="deprecation"; type="text/plain"
```
The linked resource may contain information about the deprecation that happened in the specified date (e.g. introducing a new endpoint replacing the one the client is currently using), sharing details about it. Since this information is not useful for users, a client is not required to show it and may choose to collect it and report it to its developers or administration team. In case the scope of the deprecation is broader than the specific action, this information might be added to the linked resource. These information are meant as helpful way to armonize server and clients versions, and they might be ignored by the client.