Expedia Affiliate Network Hotel API v3 Integration Tutorial. Part 1.04.04.2012

Introduction

In this tutorial I’ll try to walk you through the process of creating a simple interface with the Expedia
Affiliate Network Hotel API (version 3) using PilotFish XCS eiConsole. More precisely, we are going to
create an interface to get the list of the available hotels by the defined set of parameters. This tutorial
have a set of illustration that would help you to understand how to do it yourself.

Setting up the environment

Before we start you need to download the latest version of the XCS eiConsole from the PilotFish
Technology web site (http://pilotfishtechnology.com/). XCS eiConsole is the sophisticated IDE to create
interfaces of any complexity between disparate systems. You can read more about it on the PilotFish
Technology web site mentioned above. The XCS eiConsole IDE is available for 90 day evaluation period.

Expedia Affiliate Network Hotel API

In this section we will briefly review the API (version 3) of the EAN for Hotels. Version 3 is the latest and
the most modern version of the EAN API. It supports 4 different protocols of collaboration – XML, JSON,
REST and SOAP, so the user can shoes whatever is convenient for specific integration situation. In this
tutorial we will use SOAP-based approach.
The Hotel API allows performing the following operations:
● Request Hotel List
● Request Hotel Information
● Location Geo Functions
● Request Hotel Rooms
● Request Rate Rules
● Request Payment Types
● Book a Reservation
● Request Itinerary Record
● Cancel a Reservation
For our sample we will request the hotels list from the EAN.
You can read more about the EAN API at http://developer.ean.com/docs/read/hotels/Version_3.

Creating the interface

First start of the XCS eiConsole

If you are familiar with the XCS eiConsole, you can skip this section.
Before you can get to the XCS eiCnsole itself, you need to enter your licensing credentials. You suppose
to get them from the PilotFIsh Technology via email. After that you will be prompted with the getting
started dialog with the links to the overview and tutorial videos. I would strongly recommend you to
watch them before moving to the next steps. The main screen of the XCS eiConsole is the file
management dialog. We can logically split this dialog into two functional parts. The top one is the
interface management part. It has two views — the basic one and advanced one. The basic view is
sufficient for most of the cases and we will use only this view in the tutorial. In the basic view u can see
the list of the routes and interfaces in your working directory (aka workspace). By default, the ’Getting
Started’ working directory will be selected for you automatically on the first start. We recommend
changing it to the new directory by clicking Browse button.

The route is the main piece of logic in the interface. It allows connecting any number of source systems
to any number of target systems. It is designed using the conversion over configuration, where each
route has 7 stages that you can configure. You can read more about it on the PilotFish Technology web
site.

Interface Definition

The interface that we are going to create is pretty simple. As we mentioned above, it will need to
connect to the EAN and get the list of the hotels. For educational purposes, let’s assume that we should
get the data from the file on the hard drive. This file is defined in the custom XML. And after getting the
response we will need to transform it to the HTML file and send it via email.
The error handling should be on place too. So, if we get the response from EAN that contains an error,
it should be reported via email. If error is happened during interface execution, it should also be caught
and sent to the same email.

Interface Implementation

As we mentioned above, we are going to use SOAP web services to perform calls to the EAN Hotels API.
Thus, the final interface would need to have the following routes (note that the names of the routes and
interfaces are completely up to you):
1. ‘EAN_Hotels_HotelsList_DataSource‘ – this route is going to pick up the data in the source
directory on the hard drive, transform this data to the appropriate XML document, acceptable
by the Expedia API and send it to the next route called ‘EAN_Hotels_HotelsList_Request’.
2. ‘EAN_Hotels_HotelsList_Request’ – this route gets the data from the previous route and sends
the data to the SOAP web service of the EAN API. Received response is forwarded to the
route ‘EAN_Hotels_HotelsList_ResponseHandler’.
3. ‘EAN_Hotels_HotelsList_ResponseHandler‘ – waits for response from the EAN API, sent
by ‘EAN_Hotels_HotelsList_Request’ route. Checks if the response has an error (returned by
API) and if so – forwards the response data to the ‘EAN_Hotels_HotelsList_ErrorHandler’ route.
If there’s no error in the response – transform response to the HTML file and send it to the
specified email address.
4. ‘EAN_Hotels_HotelsList_ErrorHandler‘ – receives the error information and sends it to the
specified email.
Each of these routes will be reviewed in details in the next chapters.

Route ‘EAN_Hotels_HotelsList_DataSource’

To add a route you need to go to the main menu of the file management dialog: Edit -> Add Route… Or
you can click Shift+R. Enter the name of the route (as I mentioned earlier, you may not follow the route
names from this tutorial) and click OK. You will see the route with appropriate name in the table with of
the Basic View. You may notice that it is highlighted with the slightly red color. It means that route is not
fully configured to work properly. So let’s get rid of this redness and configure this part of the interface.
To open the route configuration window you need to double-
click on the appropriate table item. Route editing dialog will
appear.


As you may see, it consists of seven stages. Each one is responsible for its own part of the process. For
example, Listener gets the data from its location, target transformation transforms the data to the
format of the target system etc.. If you are not familiar with the route editing topology grid, you need to
watch the tutorial or read documentation on the PIlotFIsh Technology web site.
As you remember from the previous section of the tutorial, this route is responsible for picking up the
data from the data source, transforming it into the proper EAN XML and sending them to the next route
for processing.
Let’s start with Listener. Click Add Source button and click on the Listener stage in the topology grid.
This is the place where we can specify the Listener for this source system. Select Directory from
the ‘Listener Type’ dropdown. Directory listener configuration panel will appear. There are a few
required parameters, such as pooling interval and pooling directory. Let’s set the pooling interval to 10
seconds. It meant that this listener will check for the new files every 10 seconds in the specified pooling
directory. Choosing the pooling directory is up to you. Here’s the screenshot of the configured directory
listener.


Now let’s move to the transformation step. The format in which the data is stored in the input file
is the format of the source system, thus we need to transform it to the canonical format. In case of
this interface, the canonical format is the format of the XML stat we are going to send to the EAN
web services. For the route design it means that we should perform the transformation on the source
transformation stage.


Let’s select Source Transform cell in the topology grid. Here we need to add the Format Profile, which is
the reusable component inside the route that is responsible for performing the transformations.
Click ‘Add Format’ button and enter name ‘DataSourceToEANXML’. Now we can see two sub stages:
http://en.wikipedia.org/wiki/XSLT.
In our case the XSLT will be responsible for transforming the source XML to the XML of an appropriate
format for EAN. Of course, you should not write this XSLT by hands (although you can if you want
to). There’s a XCS Data Mapper – one of the most functional and user-friendly application to create
mappings from one tree-view format to another tree-view format. To open it, uncheck the ‘Use Direct
Relay’ checkbox and click Edit button.

Creating the mapping

Below you can see the screenshot of the just-opened XCS Data
Mapper.


The data mapper consists of three main parts. On the left-hand side you can see the source format tree
panel. On the right-hand side – target format tree panel. In the center of the application we see the
mapping panel, which is the graphical representation of the XSLT mapping. On the top of this panel you
can see the palette with main XSLT, XPath and other components that might be necessary for creating
you mapping. Also, you can switch to the XSLT view, to the testing mode and even debug the created
XSLT transformation. In this tutorial we will not cover the entire Data Mapper functionality – it would
take like a hundred pages of this document. If you want to know more about its abilities, you can read
it on the appropriate page of the PilotFish web site — http://pilotfishtechnology.com/products/xml-
transformation/xml-data-mapping/.
So, our next task is to load the source and target formats to the Data Mapper. To load the source format
you need to click the ‘Open Source Format’ button.


If will open the dialog with the list of the available format builders.


Format builder is the module that can build the format from the specific type of file(s). Data Mapper has
a set of default format builder for popular common formats, but some of the custom format builders
can be downloaded from the PilotFish Interface Exchange (http://pie.pilotfishtechnology.com).
We remember that our source file is the XML file, so let’s use the XML format builder. Select it in the
dropdown and specify the file (it is delivered in the ‘data’ folder of the interface). This file is pretty
simple because in this tutorial we just want to give you a quick overview on how you can create such
interface yourself.

<?xml version=”1.0″ encoding=”UTF-8″?>
<MyAddressInfo>
<city>New York</city>
<country>US</country>
<arrive_at>04/01/2012</arrive_at>
<departure_at>04/02/2012</departure_at>
</MyAddressInfo>

So, after building this XML file in the appropriate format builder you will see the source format. In this
case it would consist of the same root node and four child nodes.


Now we need to build the target format. We can get the information about target format from the
WSDL (Web Service Description Language) file that is provided by Expedia Affiliate Network. You can
find it in the ‘data’ folder of the interface. To build the format we need to use the WSDL format builder.


The result format would look like this:


We need to create the mapping. For creation relationship between Source and Target format
you simply drag and drop them together into the Mapping pane. Usually you first take fields from Target
tree then set into it values from Source or create your custom values. In this example we add additional
necessary for EAN API information.

Continuation will be in next posts.