2. Protocol and error handling¶
2.1. Request and response¶
An AlpineBits® compliant server exposes a single HTTPS URL. Clients send POST requests to that URL.
The POST request must transmit the access credentials using basic access authentication.
The HTTPS header of the POST request must contain an X-AlpineBits-ClientProtocolVersion field. The value of this field is the protocol version supported by the client (see the first column of the changelog table). A server that does not receive the field will simply conclude that the client speaks a protocol version preceding 2013-04.
The HTTPS header of the POST request may contain an X-AlpineBits-ClientID field. The value of this field is an arbitrary string which a server implementer might want to use to identify the client software version or installation ID.
The POST request must follow the multipart/form-data encoding scheme, as commonly used in the context of HTML forms for file uploads.
The POST request may be compressed using the gzip algorithm, in which case the HTTP request header Content-Encoding must be present and have "gzip" as a value. A POST request compressed with gzip must be compressed by the client in its entirety (i.e. the whole message must be compressed, not the single parts of the multipart/form-data content). It is the responsibility of the client to check whether the server supports content compression, this is done by checking the value of the HTTP response header X-AlpineBits-Server-Accept-Encoding which is set to "gzip" by servers which support this feature. The so called "Handshaking" actions must not be compressed.
The POST requests must have at least one parameter named action. Depending on the value of action, one additional parameter named request might be required.
A exemplary handshake on command line using cURL with file samples/Handshake-OTA_PingRQ.xml would look as follows.
curl --trace-ascii - -H "X-AlpineBits-ClientProtocolVersion: 2024-10" --user user:secret -F "action=OTA_Ping:Handshaking" -F "request=<Handshake-OTA_PingRQ.xml" http://development.alpinebits.org/server-2024-10/ |
Following is the capture of the example POST from the command above. The first value of action is the string action_OTA_Ping, indicating the client wishes to perform the handshake, and the rest of the action listed in samples/Handshake-OTA_PingRQ.xml. The value of request is an XML document (not fully shown).
POST /server-2024-10/ HTTP/1.1 Host: development.alpinebits.org Authorization: Basic Y2hyaXM6c2VjcmV0 User-Agent: curl/7.64.0 Accept: / X-AlpineBits-ClientProtocolVersion: 2024-10 Content-Length: 1472 Content-Type: multipart/form-data; boundary=cd287e7912d06e8f Expect: 100-continue --cd287e7912d06e8f Content-Disposition: form-data; name="action" OTA_Ping:Handshaking --cd287e7912d06e8f Content-Disposition: form-data; name="request" Content-Type: application/xml [here is the content of the file Handshake-OTA_PingRQ.xml] --cd287e7912d06e8f-- |
Note the Authorization field, with the username/password string (user:secret) encoded in base64 (Y2hyaXM6c2VjcmV0) as defined by the basic access authentication standard 1.
Also note the X-AlpineBits-ClientProtocolVersion and X-AlpineBits-ClientID fields and the multipart content with the values of parameters action and request.
As a result of the POST request, the server answers with a response. Of course, the content of the response depends on the POSTed parameters, in particular the value of action. AlpineBits® currently identifies two kinds of actions: the so-called handshaking actions explained in section 3 and the actual data exchange actions explained in section 4.
HTTP/1.1 200 OK Date: Thu, 21 Oct 2024 15:16:42 GMT Server: Apache X-Powered-By: Express Access-Control-Allow-Origin: * Content-Type: application/xml; charset=utf-8 Content-Length: 1653 ETag: W/"675-SunhP4r+79pVYE64e5ahe7LFpDs" Vary: Accept-Encoding X-AlpineBits-Server-Accept-Encoding: gzip [here is the response, that is identical to Handshake-OTA_PingRS.xml in the samples] |
2.2. HTTP status codes¶
AlpineBits® uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicates success. Codes in the 4xx range indicate an error that occurred given the information provided (e.g., a required parameter was omitted, validation errors, etc.). Codes in the 5xx range indicates an error with the AlpineBits server and the client should retry.
-
When authentication fails, the server must return a status code 401 along with an error message in the form of
text/plainprefixed withERROR:. -
If any preconditions fail before data validation, the server must return a status code 400 along with an error message in the form of
text/plainprefixed withERROR:. -
Other validations must be returned in the form of XML within the corresponding OTA response element, with a status code 200.
2.2.1. Authentication¶
No valid basic auth credentials provided.
401 Unauthorized
ERROR:invalid or missing username/password
2.2.2. Server Validation¶
Missing Client Protocol Version
No valid HTTP Header X-AlpineBits-ClientProtocolVersion provided.
400 Bad Request
ERROR:no valid client protocol version provided
Unsupported Client Protocol Version
400 Bad Request
ERROR:your current alpinebits version does not match one of the servers supported versions
Missing Client ID
(optional) No valid HTTP Header X-AlpineBits-ClientID provided.
400 Bad Request
ERROR:no valid client id provided
Unsupported GZIP compression
(optional) The server does not support requests compressed with gzip. A client can verify this by checking for the presence of the HTTP response header X-AlpineBits-Server-Accept-Encoding set to gzip.
400 Bad Request
ERROR:unsupported GZIP compression
Unknown or missing action
400 Bad Request
ERROR:unknown or missing action
XML validation error
400 Bad Request
ERROR:XML validation error
2.2.3. Internal Server Errors¶
Any unexpected error may include an optional message, which must be prefixed with ERROR:.
500 Internal Server Error
2.2.4. Data Validation Errors¶
If on protocol level the outcome is 200, it means the message could be processed correctly and there have not been any errors on protocol level. However the message can still contain data inconsistencies or business logic errors. These cases are explained in the dedicated Chapter 5.
200 OK
2.3. AlpineBits® responses and error handling¶
For each data exchange action the server will send a specific response.
The response document type obviously depends on the action. For instance, a FreeRooms response will be a OTA_HotelAvailNotifRS document, whereas a response to a GuestRequests message will be a OTA_ResRetrieveRS document, as listed in section 4 (see the table at the beginning of the section for an overview). The information in the response varies accordingly. E.g. a successful OTA_ResRetrieveRS response contains a ReservationsList element, whereas an OTA_HotelAvailNotifRS obviously cannot contain such an element.
What all responses have in common, however, is that they indicate the success or failure of the data exchange action. AlpineBits® distinguishes four outcomes that are modeled using the three elements provided by OTA in this context: Success, Warnings and Errors. The four outcomes are: success, advisory, warning and error and are explained in the following sections.
Responses with an AlpineBits® success outcome
The client’s request could be completely received, correctly parsed, was deemed syntactically valid and its contents could be processed successfully by the server. All business rules were satisfied. In case of a successful outcome the response contains one empty Success element, no Warnings and no Errors:
The client, in order to safeguard the validity of the transmitted data, should always make sure that the following conditions are true:
-
The XML composed by the client does represent the actual data.
-
All the checks that are indicated in this document as "client responsibility" were performed by the client.
|
The client does not need to take any further action, upon receiving a response with a successful outcome.
Responses with an AlpineBits® advisory outcome
As is the case for the successful outcome, the request could be correctly parsed, was deemed syntactically valid and could be processed successfully in its entirety. All business rules were satisfied.
However, one or more non-fatal problems were detected and the server wishes to let the client know about them.
In this case, the response contains one empty Success element followed by one or more Warning elements with the attribute Type set to 11, meaning "Advisory" according to the "Error Warning Type" (EWT) list in the OTA code list 5.
Each Warning element should contain a human readable text.
Here is an example of FreeRooms response with an advisory outcome. Let’s imagine a server that handles FreeRooms with delta messages but wishes to receive at least one full data set each 48 hours and a client that hasn’t send one in the last 48 hours. The server might then proceed to accept another delta message, but advise the client with the following response:
|
|
A server might or might not implement responses with advisory outcomes.
However, a client must recognize advisory outcomes and visualize or log the human readable text, so that the non-fatal problem can be analyzed and corrected at a later stage. Of course, there is no need to resend the message as the server has already processed it successfully.
Responses with an AlpineBits® warning outcome
The request could be correctly parsed, was deemed syntactically valid, but could not be processed successfully in its entirety, because some business rules were violated.
Some examples for messages that cause a business rule violation are:
-
A message with an unknown HotelCode.
-
A RatePlans message having overlapping Rate elements with the same InvTypeCode attribute.
-
A GuestRequests acknowledgement message with an unknown ID.
In this case, the response contains one empty Success element followed by one or more Warning elements with the attribute Type set to any value allowed by the "Error Warning Type" (EWT) list in the OTA code list 5 other than 11 ("Advisory").
Each Warning element should contain human readable text.
Here is an example of RatePlans response with an warning outcome. Let’s imagine a client that sent rate information concerning dates in the year 2107 because there was a data entry error. While the request was formally correct, the server could not process the request (and thus could not store the information about the rates) because it does not deal with dates in the distant future. So the server will proceed to refuse the request with the following warning response:
|
|
The value 3 for attribute Type stands for "Biz rule" according to the EWT.
Upon receiving an AlpineBits® warning outcome, a client must consider the request as failed in its entirety and must act accordingly. Since the request violated a business rule, there is no use to just try resending it. The client must rather escalate the failure. When run interactively, this means alerting the user. When run in an automatized way, this means alerting someone using appropriate means.
It is important to understand that despite the meaning of the word "warning" in other contexts, an AlpineBits® warning outcome indicates a failed request (due to violation of business rules). It cannot be safely ignored.
Note that AlpineBits® uses the Warnings element also for acknowledgements in the GuestRequests section (see 4.2.3). Those messages are not considered responses (as indicated by the RQ in OTA_NotifReportRQ) and are thus unrelated to the discussion in the present section.
Responses with an AlpineBits® error outcome
The request caused one or more of the following problems:
-
It could not be correctly parsed.
-
It was deemed syntactically invalid.
-
Some error occurred while processing the request.
and therefore the request could not be be processed successfully in its entirety.
In this case, the response contains one or more Error elements with the attribute Type set to 13, meaning "Application error" according to the "Error Warning Type" (EWT) list and the attribute Code set to any value allowed by the "Error Codes" list in the OTA code list 5.
Each Error element should contain a human readable text.
As an example, let’s imagine a client sends a message without the mandatory attribute HotelCode. This makes the request invalid and the server must answer with a response indicating the error outcome. Here is an example:
|
Here, the Code 321 stands for "Required field missing" according to the "Error Codes" list.
Upon receiving an AlpineBits® error outcome, a client must consider the request to be failed in its entirety and must act accordingly.
If a client software has reason to assume the problem is temporary and occurred for the first time, it might try to resend the request at a later moment (and bail out after a small number of retries with no success).
The client must then escalate the failure. When run interactively, this means alerting the user. When run in an automated way, this means alerting someone using appropriate means.
Note that a server that receives a request that is not authenticated, has missing or invalid POST parameters, will just respond with an ERROR string as explained in sections 2 and 3. Since at that point no action can be identified the request type and hence the response type is unknown and no exchange of XML documents takes place.
A server could perform additional checks after an outcome success answer (asynchronous checks). In case of inconsistencies with a previous stored state, a server may request a complete sets of data as decribed below.
Responses with a request for complete sets of data
Along with the previous response cases, a server can request the client to send a full data set right after the current communication ends. The requested data may refer to different data from that received in the originating AlpineBits® request (For instance the server may request a full transfer of Availability information upon receiving a request for Rateplans).
In this case, the response contains one or more additional elements whose type depend on the outcome of the request:
-
One or more Warning elements in case of a success, advisory or warning outcome.
-
One or more Error elements in case of an error outcome.
These elements must be empty, must have the attribute Type set to 11 (“Advisory”) and must have the mandatory attribute Status with a value chosen among the following, based on the desired complete data set:
-
Status =
ALPINEBITS_SEND_HANDSHAKEto request the handshake update -
Status =
ALPINEBITS_SEND_FREEROOMSto request the full set of free rooms data -
Status =
ALPINEBITS_SEND_RATEPLANSto request the full set of rate plans data -
Status =
ALPINEBITS_SEND_INVENTORYto request the room configuration
If the server sends more than one of such elements, they must be referred to different data types, meaning that, at the current AlpineBits® version, a server can send up to three different requests: one for each of the above Status values.
Upon receiving a response with one or more of these elements, the client should transmit the corresponding data set as soon as possible in any order (see Tips and best practice).
The server should only send requests for kind of data supported by the client (the logic by which the server keeps track of these information is beyond the scope of this specification). The client must support receiving requests regarding any data, even if it is not directly supported/handled by it. The client is free to ignore request for data it does not handle, but might process such requests as it deems more appropriate, for instance by notifying the user.
Tips and best practice
A server should not request a complete data set in response to a complete set just received regarding the same data type. In this case, a client must ignore the request.
It is a client’s responsibility to keep track of which data was requested by the server in case it receives more than one element requesting a different complete data set.
A server should use this feature with common sense and only when necessary in order to avoid useless heavy-data transfer.
A client should implement a precaution against too frequent complete set requests, for example limiting its number in a given timespan.
Some examples:
The server accepts the message and requests a full synchronization of FreeRooms data:
|
The server sends a warning together with a request for a full synchronization of RatePlans data:
|
The server sends an error together with a request for a full synchronization of Inventory and FreeRooms data:
|
2.4. Implementation tips and best practice¶
-
For maximum compatibility across different implementations AlpineBits®, implementers are asked to handle POST requests using a supporting API in their language of choice. See appendix B for more resources.
-
All POSTs to an AlpineBits® server are sent to a single URL. However, a server implementer might make more than one URL available for independent servers, such as servers with support for different versions:
-
https://server.example.com/alpinebits/2022-10 -
https://server.example.com/alpinebits/2024-10 -
etc…
-
-
Gzip compression can make a request smaller by a factor of ten, therefore it was introduced in AlpineBits® even though its usage in POST requests isn’t very common (as opposed to responses where its use is widespread). According to the various RFCs, compressing the requests is not forbidden, but there are no implementation recommendations. It was decided to use an approach major web servers were already supporting at the time of this writing.
-
When negotiating an AlpineBits® version, clients and servers should behave in the following way (this works starting from 2013-04):
-
Client: the client queries the server version, sending a header with the highest version it supports.
-
Server: if the server supports this same version, it answers with this version and the negotiation terminates successfully; otherwise the server answers with the highest version it supports.
-
Client: if the client recognizes the server version, it starts using the server version and the negotiation terminates successfully; otherwise no communication is possible, since the two parties don’t share a common version.
-