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 section 2.3 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 X-AlpineBits-Action field (string) request body and server response (XML document)

client sends its supported actions and capabilities (since 2018-10)

YES

OTA_Ping:Handshaking

OTA_PingRQ
OTA_PingRS

3.1. Client request

The request body must contain an OTA_PingRQ document.

The EchoData element is a string representing a JSON object whose rules are defined below.

As mandated by OTA, the server, additional to it’s response, must reply the content of the EchoData element identical to what the client sent. Therefore to avoid discrepancies and problems when parsing and comparing EchoData due to different indents or whitespaces, it’s advisable to transmit the EchoData JSON string as a single line, without additional spaces.

The JSON object must 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 of the supported actions listed in section 3.3.

  • A JSON array with name supports, listing all the supported capabilities for the sibling action.

The client must always include all versions he supports in the message and set the header field X-AlpineBits-ClientProtocolVersion to the highest version.

If there is no common version after the server did the intersection, no communication is possible. For more details on server responses in the handshake see section 3.2.

files/samples/Handshake/Handshake-OTA_PingRQ.xml - Handshake client request (see human readable JSON below)
{"versions":[{"version":"2026-10","actions":[{"action":"action_OTA_Read"},{"action":"action_OTA_HotelResNotif_GuestRequests"},{"action":"action_OTA_HotelResNotif_GuestRequests_StatusUpdate"},{"action":"action_OTA_HotelInvCountNotif","supports":["OTA_HotelInvCountNotif_accept_rooms","OTA_HotelInvCountNotif_accept_categories","OTA_HotelInvCountNotif_accept_deltas","OTA_HotelInvCountNotif_accept_out_of_market","OTA_HotelInvCountNotif_accept_out_of_order","OTA_HotelInvCountNotif_accept_complete_set","OTA_HotelInvCountNotif_accept_closing_seasons"]},{"action":"action_OTA_HotelDescriptiveContentNotif_Inventory","supports":["OTA_HotelDescriptiveContentNotif_Inventory_use_rooms","OTA_HotelDescriptiveContentNotif_Inventory_occupancy_children"]},{"action":"action_OTA_HotelDescriptiveContentNotif_Info"},{"action":"action_OTA_HotelDescriptiveInfo_Inventory"},{"action":"action_OTA_HotelDescriptiveInfo_Info"},{"action":"action_OTA_HotelRatePlanNotif_RatePlans","supports":["OTA_HotelRatePlanNotif_accept_ArrivalDOW","OTA_HotelRatePlanNotif_accept_DepartureDOW","OTA_HotelRatePlanNotif_accept_RatePlan_BookingRule","OTA_HotelRatePlanNotif_accept_RatePlan_RoomType_BookingRule","OTA_HotelRatePlanNotif_accept_RatePlan_mixed_BookingRule","OTA_HotelRatePlanNotif_accept_Supplements","OTA_HotelRatePlanNotif_accept_FreeNightsOffers","OTA_HotelRatePlanNotif_accept_FamilyOffers","OTA_HotelRatePlanNotif_accept_full","OTA_HotelRatePlanNotif_accept_overlay","OTA_HotelRatePlanNotif_accept_RatePlanJoin","OTA_HotelRatePlanNotif_accept_OfferRule_BookingOffset","OTA_HotelRatePlanNotif_accept_OfferRule_DOWLOS"]},{"action":"action_OTA_HotelRatePlan_BaseRates","supports":["OTA_HotelRatePlan_BaseRates_deltas"]},{"action":"action_OTA_HotelPostEventNotif_EventReports"}]},{"version":"2024-10","actions":[{"action":"action_OTA_Read"},{"action":"action_OTA_HotelRatePlan_BaseRates","supports":["OTA_HotelRatePlan_BaseRates_deltas"]},{"action":"action_OTA_HotelPostEventNotif_EventReports"}]}]}
[small]Human readable JSON extract of the request above (for readability only: transmit it as a single line string as defined above)
{
    "versions": [
        {
            "version": "2026-10",
            "actions": [
                {
                    "action": "action_OTA_Read"
                },
                {
                    "action": "action_OTA_HotelResNotif_GuestRequests"
                },
                {
                    "action": "action_OTA_HotelInvCountNotif",
                    "supports": [
                        "OTA_HotelInvCountNotif_accept_rooms",
                        "OTA_HotelInvCountNotif_accept_categories",
                        "OTA_HotelInvCountNotif_accept_deltas",
                        ...
                    ]
                },
                ...
            ]
        },
        {
            "version": "2024-10",
            "actions": [
                {
                    "action": "action_OTA_Read"
                },
                {
                    "action": "action_OTA_HotelRatePlan_BaseRates",
                    "supports": [
                        "OTA_HotelRatePlan_BaseRates_deltas"
                    ]
                },
                {
                    "action": "action_OTA_HotelPostEventNotif_EventReports"
                }
            ]
        }
    ]
}

For every successfully 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 misinterpretations, the AlpineBits® versions below 2018-10 may be part of the JSON object, but there must not be any actions array specified for them and will be ignored. 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. To avoid discrepancies and problems when parsing and comparing EchoData due to different indents or whitespaces, it’s advisable to transmit the EchoData JSON string as a single line, without additional spaces.

This assures the client that the server got and understood the complete message. In cases the server cannot process the request (e.g. due to syntax errors) he has to answer with an HTTP status 400 Bad request.

files/samples/Handshake/Handshake-OTA_PingRS.xml - Handshake server response (see full file in samples)
<Success/>
<Warnings>
  <Warning Type="11" Status="ALPINEBITS_HANDSHAKE">
    {
      "versions": [{
          "version": "2026-10",
          "actions": [{
                "action": "action_OTA_Read"
              },{
                "action": "action_OTA_HotelResNotif_GuestRequests"
              },{
                "action": "action_OTA_HotelResNotif_GuestRequests_StatusUpdate"
              },{
                "action": "action_OTA_HotelInvCountNotif",
                "supports": [
                  "OTA_HotelInvCountNotif_accept_categories",
                  "OTA_HotelInvCountNotif_accept_deltas",
                  ...]
              },
              ...
            ]
        },
        {
          "version": "2024-10",
          "actions": [{
                "action": "action_OTA_Read"
              },{
                "action": "action_OTA_HotelPostEventNotif_EventReports"
              }]
        }]
    }
  </Warning>
</Warnings>
<EchoData> Note: Return the exact same content as received by the client with PingRQ! </EchoData>

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, he must answer with a list of all compatible versions, out of the list the client sent. The response must include only versions the server supports or knows. If there are no compatible versions, the versions list is empty.

The versions list must describe what the URL the request was sent to actually serves. A server that serves earlier versions from the same URL (see section 2.1) therefore announces them as well, even though their requests use a different Content-Type: the client already declared it speaks them, and it reaches them on the same URL by sending the Content-Type of the version it addresses. Conversely, a server that dedicates one URL to each version announces, on each of them, only the versions that URL serves.

This lets a single handshake describe a partial migration, where the server has moved only some actions to the newer version, and it lets a server retire an older version gracefully: it can stop announcing it while still accepting it, so that clients migrate as they refresh their capabilities, and stop accepting it once the traffic has ceased.

If the server supports a version, but no intersection of common actions is found, the server must return an empty actions list.

For versions 2024-10 or newer the action OTA_Ping is to be considered implicit and must not be indicated in the list of supported actions.

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_full
    for prices (RatePlans), the actor accepts complete/full/new RatePlans using notif type value New

  • OTA_HotelRatePlanNotif_accept_overlay
    for prices (RatePlans), the actor accepts deltas for a RatePlan using 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 in the X-AlpineBits-Action field, 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.

    Note that its value is the version of that specific OTA message, not a single value shared by all messages: OTA assigns a version number to every message schema and it differs between messages and even between the request and the response of the same pair (e.g. in OTA2015A OTA_HotelDescriptiveContentNotifRQ is at 8.000 while its response is at 3.000). The samples that come with this document carry the OTA2015A version of the message they show, taken from the version attribute of the corresponding OTA schema file.

  • 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.

  • A client that receives an ERROR response to a handshaking request should consider that the endpoint may serve only versions earlier than 2026-10, whose requests use a different Content-Type (see section 2.1), before concluding that its own request was malformed. Since the handshaking request itself uses the Content-Type of the version the client declares, an endpoint that does not know that Content-Type cannot parse the request and cannot report the version mismatch in a meaningful way. This is the one case the handshaking action cannot negotiate on its own.

  • 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. This information is meant as a helpful way to harmonize server and client versions, and it might be ignored by the client.

3.6. Tabular representation of OTA_PingRQ

Level Element Attribute Type Cardinality

OTA_PingRQ

element

1

›

EchoData

string(1-∞)

1

See file files/schema-xsd/alpinebits.xsd in the AlpineBits® documentation kit.

3.7. Tabular representation of OTA_PingRS

Level Element Attribute Type Cardinality

OTA_PingRS

element

1

Start choice

›

Errors

element

1

› ›

Error

element

1 - 99

Type

string enum (11|13)

1

Code

0 - 1

Status

string enum (ALPINEBITS_HANDSHAKE)

0 - 1

End choice

Start choice

›

Success

element

1

›

Warnings

element

0 - 1

› ›

Warning

element

1 - ∞

Type

1

Status

string enum (ALPINEBITS_HANDSHAKE)

0 - 1

›

EchoData

string(1-∞)

1

End choice

See file files/schema-xsd/alpinebits.xsd in the AlpineBits® documentation kit.