Connecting to the Amadeus API Gateway with a Server Application

With an Amadeus Server Application, you will be providing multiple users access to the Amadeus API gateway via a server(architecture is not limited to a single server). Your server will be responsible for managing the transactions between your users and the Amadeus API gateway via the API functions provided. A conversation handle will be returned to your server when a conversation is initiated via the openConversation function provided. This conversation handle will be the link between your user and the Amadeus host system resource. Your server will be responsible for maintaining this link, as it must be referenced within the user transactions.

To facilitate simple management of the conversation handle on your server, the Amadeus API provides functions that will serialize and unserialize conversation handle.
The functions transform a conversation handle into a simple printable ASCII string (so called "serialized context" or "serialized conversation") and vice versa. The serialized context can be easily exchanged across the network between distant machines, eliminating the need for complex manipulation and maintenance of the conversation handle for your server.

When your user has completed the desired transactions, the conversation link must be terminated with the Amadeus host system via the closeConversation function provided.

Understanding the serialization concept

Before moving on to view a logical scenario for managing your conversations in a server architecture, it may be beneficial to better understand why the serialization functions provided will be of particular interest in your developments.

Although it is not mandatory that you utilize the serialization functions provided, we believe that the implementation of these functions within your application will simplify your development. Study the following development scenario of a Virtual Travel Agency to further illustrate this point;

In this instance, the Virtual Travel Agency is a web site that enables distant customers to make their travel reservation over the internet. The customers connect to the web site with their web-browser. The Agency provides their customers with information such as flight availability, flight fares, etc... Using the following Amadeus API architecture provides an easy way for the web-server to connect to the Amadeus Global Distribution System for the information required.

Consider the following conversation that might take place:

• A web browser user will connect to the web server and want to initiate a conversation.

• The web server instantiates the conversation with the API Gateway via the API Proxy, creates a user web page, and returns the corresponding web page to the user.

• The user then sends a request for some flight availability information to the web server.

• The web server uses the API Proxy to request the information from the Amadeus host system, translates the information given back into a web page, and returns the corresponding web page to the user.

• The user then decides to sell a flight from the information and sends his request to the web server.

• The web server uses the API Proxy to make the sell within the Amadeus host system, translates the response given back to a web page, and returns the corresponding web page to the user.

• Finally the user is finished and sends a request to the web server to terminate the conversation.

• The web server uses the API Proxy to terminate the conversation, creates a final web page, and returns the corresponding web page to the user.

Although the conversation in our Virtual Travel Agency seems quite simple, it becomes a bit more complex when remembering that the link between the web browser user and the Amadeus host system is the conversation handle that is returned to the web server. Meaning, that the web server is responsible for maintaining the association between the user and the appropriate conversation handle until the conversation is terminated by the user.

Having a stateful web server can certainly handle the responsibilities but may involve increased costs of creating a remanence mechanism or adding on off-the-shelf plug-ins to make the server stateful. Not to mention, that the stateful web server will not be reliable in the case of a server crash nor will it provide the ability to load balance because of its' lack of scalability.

In addition, imagine if this Virtual Travel Agency were dealing with a distributed environment containing a farm of web servers. The implementation of the API in such an environment would be very difficult and could be very costly.
Serialization becomes the clear choice to minimize development efforts and make the Virtual Travel Agency most reliable and efficient in any environment. Here's how:

• The web server uses the API Proxy to locally serialize and unserialize the conversation handle for each transaction it receives from the user.

• The conversation handle becomes a printable string of ASCII text that is easily and transparently transported across multiple networks by being incorporated into the web pages that are sent between the web server and the browser user.

• Each new request that is sent to the web server automatically contains the serialized conversation handle from the previous transaction which allows any web server to locally unserialize it and obtain the real conversation handle to be passed through to the Amadeus host system by the API Proxy.

Reconsider the Virtual Travel Agency Conversation with this concept:

• When the user initiates the conversation (request A), the web server will connect to the Amadeus host system via the API Proxy.

• When the conversation handle is returned (CH 1), the web server will send it back to the API Proxy and request that it be serialized.

• The serialized conversation handle (SC 1) is returned from the API Proxy, the web server creates a web page with the SC 1 encapsulated within it, and returns the appropriate web page to the user.

• New transactions that are sent to the web server from the user have the associated serialized conversation handle (i.e., SC1, SC2, SC3, etc) from the last transaction processed. The conversation handle evolves with each transaction processed. Therefore, the conversation handle for each transaction must be serialized to be sent back to the user. In the case where multiple transactions are processed by the web server prior to sending a reply to the user, only the last conversation handle prior to the reply needs to be serialized to capture the latest information.

• With each request from the user, the web server first requests the API Proxy to unserialize the information and return the original conversation handle (CH 1) for referencing within the transactions to be sent to the Amadeus host system.

• When the last response is received from the Amadeus host system, the web server will again request the conversation handle (CH 1) to be serialized prior to creating the web page and returning it to the user.




• Upon receiving the termination request from the user, the web server retrieves the original conversation handle and sends the request to the Amadeus host system. Being that this is the close of the conversation, no further serialization is required.

The benefits of using the serialization functions are enormous.

Logical Scenario

A logical scenario from an Server Application to open a conversation, request multiple information, and close a conversation follows:

Conversation_handle = openConversation(connection_parameters)
Serialized_handle   = serializeConversation(Conversation_handle)

Send response to the user

Conversation_handle = unserializeConversation(Serialized_handle)
doTransaction1(Conversation_handle, query, response)
doTransaction2(Conversation_handle, query, response)
...
doTransactionN(Conversation_handle, query, response)
Serialized_handle = serializeConversation(Conversation_handle)



Send response to the user

...

Conversation_handle = unserializeConversation(Serialized_handle)
closeConversation(Conversation_handle)


Send response to the user

It is possible to perform transactions in parallel using several conversations.

Multi-threaded application considerations

In a typical server application, many users will be connected to the server application at the same time. These users will be sending queries, and receiving replies, simultaneously. The typical application will therefore need to be multi-threaded, and manage many conversations in parallel. It is perfectly valid for multiple simultaneous threads to work with multiple API conversations in parallel. There is one impotant consideration to note however.

Multi-threaded Client applications should take care that multiple simultaneous threads, do not use the same Conversation handle, at the same time.

If this occurs, the following behavoir may be observed, and should be avoided:

• The API proxy locks the conversation and protects itself from multiple sends.
  E.g. Thread 1 with ConversationHdle1 calls CAI_SendAndReceiveXML, and waits for a reply. Meanwhile Thread 2 also with ConversationHdle1 calls CAI_SendAndReceiveXML. The call in Thread2 will be rejected with 'ENTRY IN PROGRESS' as the API Proxy has locked ConversationHdle1. ConversationHdle1 has been locked by Thread1.
• The API proxy cannot lock and protect conversations during a 'hard' close.
  E.g. Thread 1 with ConversationHdle1 calls CAI_SendAndReceiveXML, and waits for a reply. Meanwhile Thread 2 also with ConversationHdle1 calls CAI_CloseConversation or CAI_CloseConversationFromFactory - The call in Thread2 will not be rejected. It is a 'hard' close. Thread1's behaviour will now become unpredictable!

Conversation Management with API Functions

• CAI_openConversationByCorporateId
• CAI_openConversationByAtid
• CAI_openPassiveConversation
• CAI_openConversationFromFactory
• CAI_initFlatConversation
• CAI_initAuthentication
• CAI_initConnection
• CAI_initOpenType
• CAI_initCustomSign
• CAI_releaseFlatConversation
• CAI_releaseConversationFactory
• CAI_releaseXXXInput
• CAI_releaseXXXInput
• CAI_serializeConversation
• CAI_unserializeConversation
• CAI_serializeConversationFromFactory
• CAI_unserializedConversationFromFactory
• CAI_closeConversation
• CAI_closeConversationFromFactory
• CAI_getVersion
• CAI_getErrorStr
• CAI_sendAndReceiveXML