What's New in v1.2

Version 1.2 of the Redeam Booking API introduces several improvements to enhance the functionality and usability of the API:

• Contact object definition has been added
• Supplier objects now contain the properties Contacts and BusinessType
• Product objects now contain the property OtherLocations
• Multiple properties have been deprecated in Location objects
• Location objects now contain the property Website
• Address objects now require the property Region to be set
• Address objects now contain the property GooglePlaceId
• Hours objects now contain the property Timezone
• BookingItem objects now contain the property Id
• BookingTraveler object property Type has been deprecated
• BookingTicket object property BookingItemId has been changed to BookingItemIds
• BookingTicket object property Status has been converted from an integer code to a descriptive string
• BookingTicketGuests objects now contain the property TypeModifier
• BookingTraveler objects now contain the property Modifier

The remainder of this document provides more detailed information describing each change and API reference links for further information.

Contact object definition

A new component object, Contact, has been introduced in version 1.2. The purpose of its introduction is to extend and consolidate all contact information for various products and suppliers. Its signature is as follows:

Supplier objects contain Contacts and BusinessType properties

In version 1.2, we're extending the Supplier object by adding the ability for suppliers to store a list of contacts and a collection of tags/keywords that describe their business:

Product objects contain OtherLocations property

Originally, multi-location support was limited to Supplier objects - it was envisioned that suppliers might maintain multiple places of physical presence, but Product objects were only allocated one Location property because they were presumed to need only the location to which guests report in order to redeem their Booking.

Use cases have emerged where this presumption does not apply (multi-museum tickets, for example). In order to support these use cases, version 1.2 adds the OtherLocations property:

Multiple Location object properties deprecated

Several properties in the Location object have been deprecated in version 1.2 and superseded with properties that are more capable or are in more logical locations. All properties are type string; no validations are performed unless noted.

Location objects contain Website property

In addition to the changes listed above, the Location object has also been extended with the inclusion of a Website property. This property is intended to store the URL to be used by guests or other interested parties to retrieve information about the supplier or product represented by the Location's parent object.

Address objects require Region property

Due to the deprecation of the Location.State property, the corresponding property Address.Region is now required. See above for more information.

Address objects contain GooglePlaceId property

Google has established and populated a vast database of information on various buildings, areas, and places of interest. In order to leverage their work and better integrate with their Reserve with Google services, we've added a property to the Address object in which to store a reference key to their placeId database.

Hours objects contain Timezone property

UTC can be an easy way to compare times globally, but the world works in local time. Jurisdictional differences in the observance of summer time/DST can make the creation and interpretation of rates and prices very confusing if only UTC time data are provided.

Consider a situation where an operator in a location that observes summer time needs to create a new Rate - the operator would take the applicable times, mutate them using the UTC offset when the rate is added, and use them to create the Rate. In this situation, resellers must use the creation date from the Rate object and the location from the Product or Supplier object to determine the local time data (presuming the location is provided and accurate - it is not required). This situation could be mitigated in previous versions of the API, but doing so required operators to create an new set of Rate objects for each local time change.

To rectify this situation, Redeam has added an optional Timezone field to the Hours object. The inclusion of this field makes all local time data fully explicit and eliminates the possibility that this confusion will occur. If no value is provided, the default value of UTC results in behavior consistent with previous versions.

BookingTraveler object property Type deprecated

Each BookingItem has a Traveler property (type BookingTraveler) which contains information about the guest to which the BookingItem pertains. In practice, many reservations are made with only the lead traveler's guest information provided, so the BookingTraveler object data is identical for each BookingItem, with the exception of a field used to denote the guest's age for the purpose of rate verification.

In previous versions of the API, the field Type was used for this purpose; it stored a string value representing the age band of the traveler - ADULT, CHILD, SENIOR, etc. Starting with version 1.2, the Type field is no longer used; instead, the BookingTraveler object's Age field now represents the actual age of the BookingItem guest.

This modification serves two purposes:

• First, it alleviates the need for users of the API to use a lookup table in order to determine the exact string values to use and the ages to which they correspond.
• Second, it allows operators to customize their rates to different age groups as they see fit instead of being forced to use fixed age bands that are quantized in a way that may not conform to their needs.

BookingItem objects contain Id property

As originally designed, it was anticipated that access to the Items collection of a Booking object would be sufficient and that access to individual booking items would not be necessary. Use cases have since emerged where individual item access would be beneficial; consequently, each booking item now contains an Id property which is assigned a unique identifier (UUIDv4) upon creation.

BookingTicket supports multiple BookingItem ids

In tandem with the addition of Id properties to individual BookingItem objects, BookingTicket property BookingItemId (previously intended only for internal use) has been modified for version 1.2. This property is now labeled BookingItemIds; as the name change implies, it has been repurposed to be a collection of string ids instead of a singular string. Upon object creation, this collection is populated with the Id from each BookingItem to which the ticket applies.

BookingTicket status codes are descriptive strings

Previous versions of the API encoded BookingTicket property Status as an integer; starting with version 1.2, this property will be encoded as a descriptive string. A chart detailing the former integer codes and the new string values to which they correlate is presented below - the intent of this change is to allow our API users to understand the meaning of the status values without its assistance.

BookingTicketGuests objects contain TypeModifier property

Previous versions of the API did not provide any way to categorize BookingTicket guest types aside from the age bands represented by the TypeCode property. Starting with version 1.2, each BookingTicketGuests object contains a property to capture this information: TypeModifier. When applicable, it can be populated with one of the enumerated values listed in the table below.

BookingTraveler objects contain Modifier property

Very similar to above, previous versions of the API did not provide any way to categorize RatePrice traveler types aside from the age bands represented by the AgeBand property. Starting with version 1.2, each BookingTraveler object contains a property to capture this information: Modifier. When applicable, it can be populated with one of the enumerated values listed in the table below.