Client Based XML Interface
API Architecture
System Scope Document
Contents
1
INTRODUCTION........................................................................................................................ 3
1.1
Overview ............................................................................................................................................. 3
1.2
Purpose of this document ................................................................................................................... 3
1.3
Simplified Client interface ................................................................................................................... 3
1.4
Client requirements ............................................................................................................................ 3
1.5
API XML Messages .............................................................................................................................. 3
2
CLIENT AUTHENTICATION ................................................................................................... 4
2.1
Overview ............................................................................................................................................. 4
2.2
Client registration ............................................................................................................................... 4
2.3
Existing GTA authority ......................................................................................................................... 4
2.4
Additional API authority ...................................................................................................................... 4
2.5
Client Authentication .......................................................................................................................... 4
2.6
Audit logging ....................................................................................................................................... 6
3
XML REQUESTS......................................................................................................................... 7
3.1
Overview ............................................................................................................................................. 7
3.2
Request top-level element .................................................................................................................. 7
3.3
Source sub-element ............................................................................................................................ 7
3.4
RequestDetails sub-element ............................................................................................................... 8
4
XML RESPONSES..................................................................................................................... 10
4.1
Overview ........................................................................................................................................... 10
4.2
Response top-level element .............................................................................................................. 10
4.3
ResponseDetails sub-element ........................................................................................................... 10
5
5.1
REQUEST MODES ................................................................................................................... 11
Overview ........................................................................................................................................... 11
API Architecture 1.4
Page 1 of 26
5.2
Request mode and response URL ...................................................................................................... 11
5.3
Synchronous XML requests ............................................................................................................... 11
5.4
Asynchronous XML requests ............................................................................................................. 13
5.5
XML Error responses ......................................................................................................................... 17
6
REQUEST / RESPONSE SCENARIOS .................................................................................. 18
6.1
Overview ........................................................................................................................................... 18
6.2
Responding to a SYNCHRONOUS request .......................................................................................... 18
6.3
Responding to an ASYNCHRONOUS request – no ResponseURL ........................................................ 18
6.4
Responding to an ASYNCHRONOUS request – with ResponseURL ..................................................... 20
6.5
Pushing updates ................................................................................................................................ 21
6.6
The multi-action request ................................................................................................................... 23
7
REQUEST SCHEMA ................................................................................................................. 26
7.1
Overview ........................................................................................................................................... 26
7.2
XML Request schema ........................................................................................................................ 26
API Architecture 1.4
Page 2 of 26
Introduction
1 Introduction
1.1 Overview
It is intended to make the GTA search and booking facilities available to registered clients
through an XML based interface.
To achieve this an Application Programming Interface (API) will be provided to allow various
types of client systems to integrate with the GTA system using a set of published XML
messages defined using the XML Schema standards.
1.2 Purpose of this document
The purpose of this document is to outline the general structure of the API, standard
functions that it will provide and specific functions that will be made available through it.
1.3 Simplified Client interface
The API will use standard HTTPS protocols replacing previous GTA offerings based on MQ
Series – all that will be needed is an HTTPS POST request.
This will give the following advantages: 



Industry standard protocols
No additional components required (e.g. MQ Series)
Security established through use of SSL
“Push” technology provided by a more efficient mechanism for receiving
asynchronous responses.
1.4 Client requirements




Client requests must be issued from a public, static IP address registered with GTA.
Client requests must be made via an HTTPS POST request.
SSL.
All data sent and received via the interface will be encoded in UTF-8.
1.5 API XML Messages
Initially it is intended to process the following XML Messages through the API: 


Static Data requests
Search requests
Booking requests
Please refer to the appropriate document for further details.
API Architecture 1.4
Page 3 of 26
Client Authentication
2 Client Authentication
2.1 Overview
The client must be registered to participate through the API. Part of the registration process
will be to record and authorise client information in order to allow them through the
authentication process.
Once a client is registered they can be authorised to all or a subset of functions made
available through the API – part of the authentication process will be to ensure the client is
also allowed to the specific function they are requesting.
Requests made to the API will be logged for audit purposes.
2.2 Client registration
Because the API will be restricted to registered clients, the GTA system must know who is
making a request. To achieve this, GTA will hold the following client information: 


E-mail address
Password associated with the e-mail address
A list of one or more IP Addresses from which the client is allowed to make requests
using the e-mail address/password combination.
2.3 Existing GTA authority
Currently the system holds information to allow authority checking for e-mail / client /
password combination. In turn this can be used to establish what functions the logged on
user is authorised to. The new API will make use of these system features.
2.4 Additional API authority
In addition to the existing authority checking, the API must also ensure the client is making
the request from a valid IP Address. Therefore a new Client to IP Address mapping is
required.
If a request is received for a Client from an invalid IP Address, it will be immediately rejected
(HTTP response 403 – Forbidden).
A process will also be required to maintain a record of invalid authentication checks for a
client from a valid IP Address, so if someone attempts to break into the system they are only
given a limited number of attempts before the email Address is disabled.
2.5 Client Authentication
2.5.1 IP Address
Because sensitive client information (i.e. client password) will be sent over the web, each
XML request will be made over a secure connection (HTTPS) and received by the new API
running on a Server. The API will determine the IP Address of the requestor.
API Architecture 1.4
Page 4 of 26
Client Authentication
2.5.2
Requested Function
<RequestDetails>
<SearchCurrencyRequest/>
</RequestDetails>
Within the RequestDetails element at least one request function must exist. The example
above shows the SearchCurrencyRequest is being requested.
The API will use the request function(s) as part of the authority checking.
The request function will be made up of: 


The action (i.e. “Search”)
What the action should process (i.e. “Currency”)
“Request” – to identify the XML as a request.
2.5.2.1 Request Function Actions
The following Actions will be recognised by the API:
Action
Add
Cancel
Modify
Search
Description
A request to add information.
A request to cancel existing information.
A request to modify existing information.
A request to receive a list of information based on search criteria
provided.
2.5.2.2 Request Function Process
The request function process refers to the part of the API system that is to be actioned upon
(i.e. Currency, Booking, BookingItem etc.).
2.5.3 Email, client and password
Each request made by the client must contain authentication parameters (held within the
Source element of the XML). The XML sample data below is for a client 123456 with an
email address of clientName@client.co.uk with a password of clientPassword.
<Source>
<RequestorID Client="123456" EMailAddress="clientName@client.co.uk"
Password="clientPassword" />
<RequestorPreferences>
<RequestMode>ASYNCHRONOUS</RequestMode>
<ResponseURL>/ProcessResponse/GetXML</ResponseURL>
</RequestorPreferences>
</Source>
2.5.4 Authority checking
The API will ensure a registered client is making an authorised request by carrying out the
following authority checks: 



Check the client and email address are known.
Check the client has registered the IP Address for use.
Check the password provided is correct (this is case-sensitive).
Check the client is authorised to the function being requested.
API Architecture 1.4
Page 5 of 26
Client Authentication
2.5.5 Valid Identification
After successful authentication, the API will proceed with the request.
2.5.6 Invalid Identification
If the parameters received for the request are invalid, a corresponding XML error response is
returned.
2.5.7 Consecutive invalid Identification attempts
If a number of consecutive invalid attempts (maybe five) is made from a valid IP Address for
the same email address (i.e. the password is invalid), then the email Address will be
disabled and no further requests allowed until the registration details have been reauthorised.
An email will be automatically sent to the disabled email address informing the user of the
action along with instructions of the procedure required to have the email re-authorised.
2.6 Audit logging
All requests made to the API will be logged.
API Architecture 1.4
Page 6 of 26
XML Requests
3 XML Requests
3.1 Overview
XML requests must be in a form expected by the API, if they are not they will be rejected and
a corresponding XML error message returned.
Each XML request message will have a top-level element of Request.
3.2 Request top-level element
Each request sent to the API must be contained within a Request element. The Request
element itself must contain the following two sub-elements: 

Source
RequestDetails
<?xml version="1.0" encoding="UTF-8"?>
<Request>
<Source>
<RequestorID Client="123456" EMailAddress="clientName@client.co.uk"
Password="clientPassword" />
<RequestorPreferences>
<RequestMode>ASYNCHRONOUS</RequestMode>
<ResponseURL>/ProcessResponse/GetXML</ResponseURL>
</RequestorPreferences>
</Source>
<RequestDetails>
<SearchCountryRequest ISO="true"/>
</RequestDetails>
</Request>
3.3 Source sub-element
<Source>
<RequestorID Client="123456" EMailAddress="clientName@client.co.uk"
Password="clientPassword" />
<RequestorPreferences>
<RequestMode>ASYNCHRONOUS</RequestMode>
<ResponseURL>/ProcessResponse/GetXML</ResponseURL>
</RequestorPreferences>
</Source>
The Source element is required to identify and authenticate the requestor and specify
definition elements for the request.
The Source element must have the following sub-elements: 

RequestorID
RequestorPreferences
API Architecture 1.4
Page 7 of 26
XML Requests
3.3.1 RequestorID sub-element
The RequestorID sub-element must have the following attributes:
Attribute
Client
EMailAddress
Password
Description
Mandatory. Used to identify the requestor.
Mandatory. Used to identify the requestor.
Mandatory. Used to authenticate the EMailAddress.
3.3.2 RequestorPreferences sub-element
The RequestorPreferences sub-element can have the following attributes/sub-elements:
Attribute
Language
ISO 639 format, no
variants
Currency
ISO 4217 format
Country
ISO 3166 format, 2
letter
Element
RequestMode
ResponseURL
Description
Optional. Used to determine the language in which the results are to be
returned. If it is not specified, the default language for the Client will be
used.
Optional. Used to determine the currency in which amounts (such as
prices) are to be returned. Constrained by currencies permitted for client.
If it is not specified, the default currency for the Client will be used. Only
ISO codes will be accepted.
Optional. Used to determine the country of residence of the passenger. As
prices may vary depending on passenger nationality it is important to
always use the correct value for this parameter to avoid price
discrepancies. If it is not specified, the default nationality for the Client will
be used. Only ISO codes will be accepted.
Description
Mandatory. Either SYNCHRONOUS or ASYNCHRONOUS. Must be valid
for the type of request (not all XML requests will have the option of both
Request Modes).
Optional. If specified gives the URL to where the response should be sent
relative to the IP Address from which the request is received (if
ASYNCHRONOUS mode has been chosen).
3.4 RequestDetails sub-element
<RequestDetails>
<SearchCountryRequest ISO="true"/>
</RequestDetails>
The specifics of each request must be contained within the RequestDetails element. For
example a simple Search Country Request will contain a single sub-element as shown
above.
3.4.1 Multiple actions within a RequestDetails sub-element
The API will allow multiple actions to be included within the RequestDetails sub-element. For
example if a client wishes to add three bookings and cancel another within a single request
the XML will take the form similar to that given below:
<?xml version="1.0" encoding="UTF-8"?>
API Architecture 1.4
Page 8 of 26
XML Requests
<Request>
<Source>
<RequestorID Client="123456" EMailAddress="clientName@client.co.uk"
Password="clientPassword" />
<RequestorPreferences>
<RequestMode>ASYNCHRONOUS</RequestMode>
<ResponseURL>/ProcessResponse/GetXML</ResponseURL>
</RequestorPreferences>
</Source>
<RequestDetails>
<AddBookingRequest>
++++ booking 1 parameters
</AddBookingRequest>
<AddBookingRequest>
++++ booking 2 parameters
</AddBookingRequest>
<AddBookingRequest>
++++ booking 3 parameters
</AddBookingRequest>
<CancelBookingRequest>
++++ booking 4 parameters
</CancelBookingRequest>
</RequestDetails>
</Request>
API Architecture 1.4
Page 9 of 26
XML Responses
4 XML Responses
4.1 Overview
The API will return XML responses in a common form.
Each XML response message will have a top-level element of Response.
4.2 Response top-level element
Each response sent by the API will be contained within a Response element.
<?xml version="1.0" encoding="UTF-8"?>
<Response ResponseReference="123456" ResponseSequence="1">
<ResponseDetails Language="en">
<SearchCountryResponse ISO="true">
++++ response details
</SearchCountryResponse>
</ResponseDetails>
</Response>
4.2.1 Response attributes
The Response element will have the following attributes:
Attribute
Description
ResponseReference The unique reference assigned by the API. Please note, that the
ResponseReference can be up to 100 characters long, with varying
character structures.
ResponseSequence Each time the API returns a response associated with a
ResponseReference it will increment the ResponseSequence by 1.
4.2.2 Response sub-elements
The Response element will contain the following two sub-elements: 

Errors (optional)
ResponseDetails
A success is indicated by the absence of the <Errors/> element.
4.3 ResponseDetails sub-element
<ResponseDetails Language="en">
<SearchCountryResponse ISO="true">
++++ response details
</SearchCountryResponse>
</ResponseDetails>
The specifics of each response will be contained within the ResponseDetails element. For
example a simple Search Country Response will contain a single sub-element as shown
above.
API Architecture 1.4
Page 10 of 26
Request Modes
5 Request Modes
5.1 Overview
XML requests made to the API will be allowed in two modes: 

Synchronous
Make the request and expect the XML response immediately.
Asynchronous
Make the request and receive back a simple XML response containing a response
reference. The full response will be produced by a background process and can be
automatically sent to the requestor (by specifying a response URL) or manually
retrieved using the request reference.
Both Synchronous and Asynchronous requests could result in an XML error response. A
common cause would be invalid or incomplete XML parameters sent in the request.
5.2 Request mode and response URL
Two important elements that can be specified within each XML message request are the
request mode and the response URL (see RequestorPreferences sub-element). These are
used to control the process flow for the request.
The API will:


Ensure the request mode is specified
Ensure the request mode and response URL are valid for the type of XML message
received
Certain types of XML message request will allow either synchronous or asynchronous
request modes. So for something like a request for hotel information either mode will be
allowed.
Other types of XML message request will be fixed. In these cases the request mode must
match the allowed request mode.
Furthermore, for an asynchronous request mode and response URL may or may not be
optional (depending on the XML message request).
5.3 Synchronous XML requests
A conversation will be established where a response is expected to be returned immediately
for an XML request. The API will recognise these types of request and process them
immediately, returning the associated formatted XML.
All synchronous request and response pairs will be allocated a unique reference and logged
to the database.
API Architecture 1.4
Page 11 of 26
Request Modes
5.3.1 Typical process flow for synchronous requests
The diagram below shows the expected path a synchronous XML request will take through
the API.
5.3.2 API – Retrieve Response for a given reference
A special synchronous request will be responsible for retrieving the results of an
asynchronous request previously made to the API (with no return URL provided). In this
API Architecture 1.4
Page 12 of 26
Request Modes
case the background process (see later for a more detailed explanation) will be responsible
for generating and queuing the response.
If the response is not ready a corresponding XML error message will be returned.
The diagram below shows the expected path this type of synchronous XML request will take
through the API.
Client
Send request
for reference
API
Background Process
Receive request
Authenticate
Assign reference
Log request
Retrieve response
for given reference
Receive response
Queue
Return response
Update response
RETRIEVED status
VISION DONE – NOT COMPLETE – TO CHECK
When the API receives an XML request it will be responsible for the following:







Authentication
As previously described.
Assign reference
An unique reference will be assigned to this request.
Log request
This request will be stored in the database.
Retrieve Response for given Reference – not ready
If the response for the given reference is not ready to be sent, a corresponding XML
error message will be returned.
Retrieve Response for given Reference – ready
If the response for the given reference is ready to be sent, the API retrieves it.
Return response
The retrieved message is returned to the client.
Update the request status
The status of the request will be updated to RETRIEVED.
5.4 Asynchronous XML requests
5.4.1 Receiving the XML Response for asynchronous requests
For asynchronous XML requests there will be two ways for the client systems to receive the
corresponding XML response:
API Architecture 1.4
Page 13 of 26
Request Modes

Automatic
This will be a process flow where after the background job has processed the client’s
request, the XML response will automatically be sent to the ResponseURL supplied
by the client within the request. Once the results have been sent successfully, the
automatic processing will be complete.
Note:
The ResponseURL provided by the client must be relative to the IP Address from
where the request is being sent. Therefore if the following XML request is received
from IP Address 123.456.789.101, the response will be returned to
123.456.789.101/ProcessResponse/GetXML.
Please also note that we only allow access to Ports 80 and 443.
<Source>
<RequestorID Client=”123456” EMailAddress="client.abc@msn.com"
Password="Cli3ntAbc" />
<RequestorPreferences Language="en" Currency="GBP">
<RequestMode>ASYNCHRONOUS</RequestMode>
<ResponseURL> /ProcessResponse/GetXML</ResponseURL>
</RequestorPreferences>
</Source>
Also the automatic processing requires the client system to have its own HTTP or
HTTPS process in place to pick up a response sent to the ResponseURL.

Requested
If a ResponseURL is not supplied within the request, the response will remain on the
Processed Queue waiting for the client to make another request to pick up the results
(see API – Retrieve Response for a given reference).
Note:
We have different retention periods for synchronous and asynchronous requests and
the corresponding responses.
These values also vary between our test server and the production system and can
be changed by us as necessary.
<Source>
<RequestorID Client=”123456” EMailAddress="client.abc@msn.com"
Password="Cli3ntAbc" />
<RequestorPreferences Language="en" Currency="GBP">
<RequestMode>ASYNCHRONOUS</RequestMode>
</RequestorPreferences>
</Source>
API Architecture 1.4
Page 14 of 26
Request Modes
5.4.2 Typical process flow for asynchronous requests
The diagram below shows the expected path an asynchronous XML request will take
through the API and background process. It does not show every possible path - including
error situations - but these are included in the detailed notes that follow.
Client
Send request
API
Background Process
Receive request
Authenticate
Assign reference
Queue
Log request
Receive reference
Return reference
Process request
Update request
PROCESSED status
Log response
Retrieve response
Receive response
Queue
Send response
Update response
SENT status
Queue
VISION READY – TO CHECK
A short conversation will be established where the client request is received, authenticated
and after a unique reference assigned it is queued for background processing. The client is
then returned the unique reference for storing against their original request (this reference
could then be used to retrieve the corresponding request - see API – Retrieve Response for
a given reference).
The following paragraphs give more detail about the diagram above.
5.4.3 API - Client asynchronous requests
When the API receives an asynchronous XML request it will be responsible for the following:


Authentication
As previously described.
Assign reference
A unique reference will be assigned to all requests. This will be used to identify the
request for any future processing.
API Architecture 1.4
Page 15 of 26
Request Modes


Log request
The request will be stored in the database. The request status will be set so that it
will queued for background processing.
Return reference
The unique reference assigned to the request is returned to the Client.
This completes the immediate processing for the request.
5.4.4 Background Process
The function of the background process is to retrieve any request with a queued status. It will
be responsible for the following:




Request validation
Validate the supplied parameters. Format an XML error if required.
Process request
Process the request and format the XML response.
Update the request status
The status of the request will be updated to PROCESSED.
Log response
The response will be stored in the database.
5.4.5 API – Automatic Response
The function of the Automatic Response process is to poll the queue of XML Responses
ready for sending. It will be responsible for the following: 


Retrieve response
Continuously poll the XML Response Queue for messages ready to be sent. When a
message is in the ready state it will be retrieved.
Send response
The retrieved message is sent to the required URL (which is specified within the
original request).
Send response – with Errors
If a message cannot be sent successfully to the required URL (e.g.: the link to the
URL times out), the number of transmission attempts will be incremented by 1 and
date/time set for when the next attempt to transmit the message should be made. As
the number of unsuccessful attempts increases so too will the period of time between
attempts to transmit. A maximum will be set for the transmission attempts.
Note:
If there is a problem with the sending of the response, the client can use the API –
Retrieve Response for a given reference process. After successfully retrieving the
message via this method, the status of the response will be updated to RETRIEVED
and will no longer be selected for automatic response.

Update the response status
After successfully sending the response the status of the response will be updated to
SENT.
API Architecture 1.4
Page 16 of 26
Request Modes
5.5 XML Error responses
The API will return a formatted XML message containing errors when the request cannot be
successfully processed.
API Architecture 1.4
Page 17 of 26
Request / Response scenarios
6 Request / Response scenarios
6.1 Overview
This section uses example situations to further explain how the API can be used in both
SYNCHRONOUS and ASYNCHRONOUS modes.
6.2 Responding to a SYNCHRONOUS request
For a SYNCHRONOUS request such as a simple Search Country Request, the client will
receive an immediate response.
For this type of request the client would send a SYNCHRONOUS XML request such as:
<?xml version="1.0" encoding="UTF-8"?>
<Request>
<Source>
<RequestorID Client="123456" EMailAddress="clientName@client.co.uk"
Password="clientPassword" />
<RequestorPreferences>
<RequestMode>SYNCHRONOUS</RequestMode>
</RequestorPreferences>
</Source>
<RequestDetails>
<SearchCountryRequest ISO="true"/>
</RequestDetails>
</Request>
And receive an immediate XML response in the following format:
<?xml version="1.0" encoding="UTF-8"?>
<Response ResponseReference="123456" ResponseSequence="1">
<ResponseDetails Language="en">
<SearchCountryResponse ISO="true">
++++ response details
</SearchCountryResponse>
</ResponseDetails>
</Response>
6.3 Responding to an ASYNCHRONOUS request – no ResponseURL
Taking the simple Search Country Request example and applying it to an
ASYNCHRONOUS request without a ResponseURL provided, the client will not receive the
results of the search immediately. Instead the immediate response given will contain a
ResponseReference (ticket number) which will subsequently be used by the client to retrieve
the results of the original request.
API Architecture 1.4
Page 18 of 26
Request / Response scenarios
6.3.1 Request/Response pair for an ASYNCHRONOUS request – no ResponseURL
For this type of request the client would send an XML request such as:
<?xml version="1.0" encoding="UTF-8"?>
<Request>
<Source>
<RequestorID Client="123456" EMailAddress="clientName@client.co.uk"
Password="clientPassword" />
<RequestorPreferences>
<RequestMode>ASYNCHRONOUS</RequestMode>
</RequestorPreferences>
</Source>
<RequestDetails>
<SearchCountryRequest ISO="true"/>
</RequestDetails>
</Request>
And receive an immediate XML response in the following format:
<?xml version="1.0" encoding="UTF-8"?>
<Response ResponseReference="123456"/>
The API would forward the request on for background processing.
6.3.2 Request/Response pair to receive corresponding results
After receiving the Response Reference for the ASYNCHRONOUS request the client can
perform an HTTP to retrieve the results. This would be made to the retrieval URL in the
format of:
Retrieval URL/RetrieveListenerServlet?TOKEN=123456
If the background process has built the required response, the API would immediately return
it to the client. The results returned would be in an identical form to those returned
immediately for a SYNCHRONOUS XML request:
<?xml version="1.0" encoding="UTF-8"?>
<Response ResponseReference="123456" ResponseSequence="1">
<ResponseDetails Language="en">
<SearchCountryResponse ISO="true">
++++ response details
</SearchCountryResponse>
</ResponseDetails>
</Response>
Note:
Once the background process has built the XML response, it is possible for the
information within it to become out of date almost immediately. Therefore the longer
the client system leaves between the original request and the request for results the
more likely it will be for the information to be stale.
API Architecture 1.4
Page 19 of 26
Request / Response scenarios
6.4 Responding to an ASYNCHRONOUS request – with ResponseURL
Taking the simple Search Country Request example again and applying it to an
ASYNCHRONOUS request with ResponseURL provided, the client will not receive the
results of the search immediately. Instead the immediate response given will contain a
ResponseReference (ticket number) which will subsequently be used by the API client to
retrieve the results of the original request.
6.4.1 Request/Response pair for an ASYNCHRONOUS request – with ResponseURL
For this type of request the client would send an XML request such as:
<?xml version="1.0" encoding="UTF-8"?>
<Request>
<Source>
<RequestorID Client="123456" EMailAddress="clientName@client.co.uk"
Password="clientPassword" />
<RequestorPreferences>
<RequestMode>ASYNCHRONOUS</RequestMode>
<ResponseURL>/ProcessResponse/GetXML</ResponseURL>
</RequestorPreferences>
</Source>
<RequestDetails>
<SearchCountryRequest ISO="true"/>
</RequestDetails>
</Request>
And receive an immediate XML response in the following format:
<?xml version="1.0" encoding="UTF-8"?>
<Response ResponseReference="123456">
</Response>
The API would forward the request on for background processing.
6.4.2 Pushing the Response containing the corresponding results
After the background process has generated the results for the given request, it will
recognise the client has supplied the ResponseURL and automatically push the response
back to the client. The results returned would again be in an identical form to those returned
immediately for a SYNCHRONOUS XML request:
<?xml version="1.0" encoding="UTF-8"?>
<Response ResponseReference="123456" ResponseSequence="1">
<ResponseDetails Language="en">
<SearchCountryResponse ISO="true">
++++ response details
</SearchCountryResponse>
</ResponseDetails>
</Response>
API Architecture 1.4
Page 20 of 26
Request / Response scenarios
6.5 Pushing updates
For certain types of request it will be possible for the client to indicate that any update that
occurs subsequent to the corresponding “pushed” response will also be pushed to the client
ResponseURL.
Obviously there would be no updates to push for something like our previous Search
Country Request example but if an example such as an Add Booking Request was to be
used the following scenario shows what information the API could automatically provide.
6.5.1 Initial ASYNCHRONOUS processing
The client would send an XML request and must provide:


RequestMode of ASYNCHRONOUS,
Specify the ResponseURL and
So the client would send an Add Booking Request in the following format:
<?xml version="1.0" encoding="UTF-8"?>
<Request>
<Source>
<RequestorID Client="123456" EMailAddress="clientName@client.co.uk"
Password="clientPassword" />
<RequestorPreferences>
<RequestMode>ASYNCHRONOUS</RequestMode>
<ResponseURL>https://215.241.21.1/ProcessResponse/GetXML</ResponseURL>
</RequestorPreferences>
</Source>
<RequestDetails>
<AddBookingRequest>
++++ booking 1 parameters
</AddBookingRequest>
</RequestDetails>
</Request>
And receive an immediate XML response in the following format:
<?xml version="1.0" encoding="UTF-8"?>
<Response ResponseReference="234567">
</Response>
The API would forward the request on for background processing.
In all cases we would prefer that you use an ‘Absolute URL’ for the Response URL value i.e.
one that starts with ‘https://…’ rather than one beginning with ‘/’. Also please bear in mind
that this URL will need to available for external access to allow us to push this response
back to your server.
API Architecture 1.4
Page 21 of 26
Request / Response scenarios
6.5.2 Pushing the Response containing the corresponding results
After the background process has generated the results for the given request, it will
automatically push the response back to the client. This response would be in the following
format:
<?xml version="1.0" encoding="UTF-8"?>
<Response ResponseReference="234567" ResponseSequence="1">
<ResponseDetails Language="en">
<BookingResponse>
++++ response details
</BookingResponse>
</ResponseDetails>
</Response>
This completes the minimum requirement when a ResponseURL is provided.
6.5.3 AutoUpdates
When auto-updates are applicable the API may or may not push additional XML responses
to the client.
If the information pushed to the client within the initial response never changes – in the
example of the booking it could be added to the system as fully confirmed and this
information included in the response received - then no additional XML responses will be
triggered.
However, in the case where a booking is added to the system awaiting confirmation, the API
will:



Return the initial response giving the initial booking information.
Be responsible for monitoring for events that update the details of the booking
When pertinent updates occur automatically send them back to the client as XML
messages using the ResponseURL.
An auto update message could be in the following format:
<?xml version="1.0" encoding="UTF-8"?>
<Response ResponseReference="234567" ResponseSequence="2">
<ResponseDetails Language="en">
<BookingResponse>
++++ response details
</BookingResponse>
</ResponseDetails>
</Response>
6.5.4 ResponseReference and ResponseSequence
For all responses relating to a given request the ResponseReference will be the same and
the ResponseSequence will start at 1 (for the initial response) and increment by 1 for each
subsequent update message.
Due to the possible use of multi-threaded request/response processing it cannot be
guaranteed that the receiver will always receive responses in exactly the same order as they
were built, so for the auto updates the client must be aware that it is possible to receive
responses for the same ResponseReference with the ResponseSequence out of sequence.
API Architecture 1.4
Page 22 of 26
Request / Response scenarios
6.6 The multi-action request
The API will allow multiple actions to be included within the RequestDetails sub-element. For
example if a client wishes to add three bookings and cancel another within a single request
the client would send XML similar to that given below:
<?xml version="1.0" encoding="UTF-8"?>
<Request>
<Source>
<RequestorID Client="123456" EMailAddress="clientName@client.co.uk"
Password="clientPassword" />
<RequestorPreferences>
<RequestMode>ASYNCHRONOUS</RequestMode>
<ResponseURL>https://214.213.24.2/ProcessResponse/GetXML</ResponseURL>
</RequestorPreferences>
</Source>
<RequestDetails>
<AddBookingRequest>
++++ booking 1 parameters
</AddBookingRequest>
<AddBookingRequest>
++++ booking 2 parameters
</AddBookingRequest>
<AddBookingRequest>
++++ booking 3 parameters
</AddBookingRequest>
<CancelBookingRequest>
++++ booking 4 parameters
</CancelBookingRequest>
</RequestDetails>
</Request>
And receive an immediate XML response in the following format:
<?xml version="1.0" encoding="UTF-8"?>
<Response ResponseReference="765432">
</Response>
All responses relating to the three AddBookingRequests and the CancelBookingRequest will
be returned under the ResponseReference of 765432.
6.6.1 Initial ASYNCHRONOUS response
The client will receive the XML responses relating to ResponseReference of 765432 in a
sequential order.
After the background process has generated the results for all the sub-request (the three
AddBookingRequests and the CancelBookingRequest), it will automatically push the
individual responses back to the client. This response would be in the following format:
<?xml version="1.0" encoding="UTF-8"?>
<Response ResponseReference="765432" ResponseSequence="1">
<ResponseDetails Language="en">
<BookingResponse>
++++ booking 1 parameters
</BookingResponse>
API Architecture 1.4
Page 23 of 26
Request / Response scenarios
</ResponseDetails>
</Response>
<?xml version="1.0" encoding="UTF-8"?>
<Response ResponseReference="765432" ResponseSequence="2">
<ResponseDetails Language="en">
<BookingResponse>
++++ booking 2 parameters
</BookingResponse>
</ResponseDetails>
</Response>
<?xml version="1.0" encoding="UTF-8"?>
<Response ResponseReference="765432" ResponseSequence="3">
<ResponseDetails Language="en">
<BookingResponse>
++++ booking 3 parameters
</BookingResponse>
</ResponseDetails>
</Response>
<?xml version="1.0" encoding="UTF-8"?>
<Response ResponseReference="765432" ResponseSequence="4">
<ResponseDetails Language="en">
<BookingResponse>
++++ booking 4 parameters
</BookingResponse>
</ResponseDetails>
</Response>
6.6.2 AutoUpdates
All auto-updates will be pushed to the client under ResponseReference 765432 for any
update to any of the above booking requests. These updates can happen in any order, so it
is possible for the client to receive the following sequence of updates:
<?xml version="1.0" encoding="UTF-8"?>
<Response ResponseReference="234567" ResponseSequence="5">
<ResponseDetails Language="en">
<BookingResponse>
++++ booking 3 parameters
</BookingResponse>
</ResponseDetails>
</Response>
<?xml version="1.0" encoding="UTF-8"?>
<Response ResponseReference="234567" ResponseSequence="7">
<ResponseDetails Language="en">
<BookingResponse>
++++ booking 2 parameters
</BookingResponse>
</ResponseDetails>
</Response>
API Architecture 1.4
Page 24 of 26
Request / Response scenarios
Note. There will always be sufficient information within the BookingResponse to
identify each individual booking.
Please refer to the Bookings document for more detail.
API Architecture 1.4
Page 25 of 26
Request Schema
7 Request Schema
7.1 Overview
This section includes extracts from the schema that define the definition of XML requests.
For a full schema definition see the API_Schema document.
7.2 XML Request schema
<?xml version="1.0" encoding="UTF-8" ?>
- <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:include schemaLocation="API_Common.xsd" />
- <xsd:element name="Request">
- <xsd:complexType>
- <xsd:sequence>
<xsd:element name="Source" type="t_Source" />
<xsd:element name="RequestDetails" type="t_RequestDetails" />
</xsd:sequence>
</xsd:complexType>
<xsd:attributeGroup ref="a_Request" />
</xsd:element>
</xsd:schema>
All requests will be made up of a Source element containing authentication parameters,
followed by a RequestDetails element containing the specifics of the request.
API Architecture 1.4
Page 26 of 26