The Holibob API - Introduction

Introduction

This documentation covers the Holibob GraphQL API that allows authorised partners to query for products and associated availability and to create and confirm bookings for these availabilities.

GraphQL uses Queries, Mutations and Subscriptions to facilitate your interactions with the Holibob eCommerce engine for experiences.

A query can look very similar to JSON but it is of note that elements are generally separated by a newline and there is no comma at the end of each line.

Before using any part of the API you will need to apply to Holibob for an appropriate holibobApiKey and holibobSecret that may be used to sign requests to the API. You will also be provided with a partner administration username and password that provide access to an administration portal "Extranet" and to any consumer-facing “white-label” websites that we operated on your behalf.

If you require additional users to be created, perhaps with limited permissions then our commercial team will be happy to facilitate this for you.

In the first instance, your channels will be restricted to sandbox mode to enable worry-free testing. You can read more about this in the section titled “Sandbox Mode”.

The focus of the development team has been to make the API as simple to integrate with as possible whilst still providing a rich interface for product content, filtering, booking and management of your data.

We are keen to work closely with you and will always ensure prompt responses to enquiries often leading to the setup of conference calls and screen-sharing sessions with our most experienced product managers and technical staff.

The Holibob GraphQL API allows authorised partners to query for products and their associated availability and to make bookings on behalf of their consumers.

The production API is available at: https://api.production.holibob.tech/graphql

Why GraphQL

We're using GraphQL because it's great for developers, partners, and merchants.

GraphQL brings:

A richly expressive open-source specification, maintained by a dedicated foundation.
Schemas and types that strictly define valid requests and responses.
Introspection, meaning you can ask any GraphQL API what it can do.
Developer tools to ease learning and integration.
The flexibility to specify exactly what data you care about, and retrieve only as much or as little data as needed.
The efficiency of combining multiple traditional REST endpoints into one request.
The freedom to use any programming language you want — and no more SDKs to manage and update on your server.

With GraphQL, we are enabling faster, safer, and more extensible integration of commerce capabilities into your product

Authentication

To access the API, you will be provided with two separate but connected elements.

These are:

API-Key: This must be passed in the header of all requests
API-Secret: This must NOT be passed in the header. It must be used to generate an HMAC signature that will be passed in the header of all requests

The required request headers are:

X-API-Key: The API-key provided to the partner by Holibob
X-Holibob-Date: The date that the request was created in a simplified extended ISO format (ISO 8601).
X-Holibob-Signature: An HMAC signature created using the API-Secret key provided to you.

Generating the signature for each request

You must create a function that will generate the x-holibob-signature and append it to the headers for every request that you send to the API.

To do this you must create a string that is the concatenation of each of the following items.

The signature is computed as the base64 encode of the SHA1 hash of the concatenated string.

The X-Holibob-Signature is created using the following technique:

Create a string by concatenating the following:
1. The Current Date - as specified in the X-Holibob-Date header.
2. The API-Key - as provided to you by Holibob
3. The Method - in upper-case will be "POST".
4. The Path - will always be "/graphql"
5. The Body - of the request
Hash the string with the SHA1 hash algorithm
Base64 encode the signature
Append the resulting value to the headers of each request with the key: X-Holibob-Signature

.You can verify that you have a valid signature by calling the welcome query. If your signature is valid the response will have an authStatus = “AUTHENTICATED” and other data in the response will confirm you PartnerName and other related details

The API call will fail if the signature is not correct, or if the date is too far in the past or future.

Example:

Let’s say we’re calling the activity search service. We want the results in English and prices in Icelandic Krona (ISK). We have the following:

X-Holibob-Date: 2013-11-09T14:33.462Z
X-API-Key: f9235a6a15c340b6b1e1cb5f3687d789 (this is not a real key and can not be used - you must use the key provided to you by Holibob)
Secret Key: 23e2c7da7f7048e5b46f96bc91324800

Now, let’s calculate the signature:

First, we concatenate the values into a canonical string in which the order of elements must be as described here:

Date = "2013-11-09T14:33.462Z"
API-key = "f9235a6a15c340b6b1e1cb5f3687d789"
Method = "POST"
Path = "/graphql"
Body = "{variables: {}, query":"query holibob {\n welcome\n}"}"

We then use this canonical string, along with the Secret to calculate the SHA1 hash for the signature, and Base64 encode it:

x-holibob-signature: HE39ukkpJXLzV+TjSi/HVYkAZ/Y=

Naming conventions

At Holibob we work tirelessly to maintain high standards across our systems and key to this are the conventions for naming entities and standardisation of syntax across the API

There are hundreds of different entities available via the API but many aspects of the API require enhanced permissions in order to access them. We are always happy to work with partners to extend access into all areas of the system as may be relevant to your particular use case.

As this document covers the most basic features relating to finding and booking products we will use only a very small number of endpoints and can refrain from introducing the more complete parts of the system.

We will be dealing with the following entities

Product - a unique record for a single Experience, Hotel, Tour or Activity complete with all of its related metadata
Availability - a unique record representing the availability to you of a Product on a given day complete with details of any options that may exist
OpinionatedAvailability - The same unique Availability detailed above but after you have provided selections for all options and pricingCategories
Booking - A unique “shopping cart” to which one or more OpinionatedAvailability may be added. A Booking will have a unique ID and you may also append your own key partnerExternalReference

Queries are available to request either a single record or a list of records. The structures available for a given item will always be the same regardless of whether you request a single item or a list of items.

For example:

You may call for productList passing one or more filters such as a City, Category, Curation or many others. The response will contain an array of product that match the filter criteria. Each item in the list will have a unique UUID
You may call for product passing the known ID for the given product. The response will contain a single Product

The simplest query

The simplest query that the API supports is the welcome query which can be run at any time in order to confirm that you have successfully connected to the API.

Query

welcome query

CODE

query {
  welcome
}

Responses

Unauthenticated Response

If you have not provided credentials by signing the request then the response will be similar to:

CODE

{
	"data": {
		"welcome": {
			"message": "Welcome to Holibob API",
			"systemTimestamp": "Thu Apr 06 2023 10:08:12 GMT+0000 (Coordinated Universal Time)",
			"authStatus": "UNAUTHENTICATED",
		}
	}
}

Authenticated Response

If you have provided credentials by signing the request then the response will be similar to:

CODE

{
  welcome:{
    message:"Welcome to Holibob API (SANDBOX)"
    systemTimestamp:"Thu Apr 06 2023 10:04:10 GMT+0000 (Coordinated Universal Time)"
    authStatus:"AUTHENTICATED"
    partnerId:"<basedOnYourCredenials>"
    partnerName:"<basedOnYourCredenials>"
    partnerChannelId:"<basedOnYourCredenials>"
    partnerChannelName:"<basedOnYourCredenials>"
    allowedCurrencies:[
      0:"GBP"
      1:"EUR"
      2:"USD"
      4:"SAR"
    ]
  }
}

Matched Response

It is also possible to send a request to some public queries (Including welcome) and pass the origin on the header.

In this case, the response will partially authenticate to a MATCHED state and will be similar to:

CODE

{
		"welcome": {
			"message": "Welcome to Holibob API",
			"systemTimestamp": "Thu Apr 06 2023 10:12:01 GMT+0000 (Coordinated Universal Time)",
			"authStatus": "MATCHED",
			"dbStage": "production",
			"saleCurrency": null,
            partnerId:"<basedOnYourCredenials>"
            partnerName:"<basedOnYourCredenials>"
            partnerChannelId:"<basedOnYourCredenials>"
            partnerChannelName:"<basedOnYourCredenials>"
  			"allowedCurrencies": [
				"EUR",
				"GBP",
				"USD"
			]
		}
	}
}

Rate Limits

Your holibob API key is associated with a usage plan that provides rate limits and quotas to protect you and us from bad actors or run-away code.

If you receive a “Limit Exceeded” error and believe this to be an error then you may contact holibob and request a rate limit increase.

The default limits are:

2 requests per second with a burst capability of 10 requests per second
2,500 requests per day

Sandbox mode

The credentials initially supplied will be valid for the production environment but limited to the “Sandbox” mode. We strongly encourage you to do all initial development against the production URL as detailed above.

In the API this can be confirmed by examination of the response from the welcome query as the isSandbox flag will be set to true.

On white-label and agent portals, you will also see an info icon on your account button.

Whilst in this mode, you are free to use the production API and portals for all testing activities including the creation and confirmation of bookings. These bookings will automatically be sandboxed and as such, they will not be confirmed with suppliers and you will not incur any charge for the bookings. All functionality is available in this state and you will be gaining access to production product and live availabilities.

All testing is therefore done against the production system ensuring that all code you write is immediately production ready.

Once you have completed initial integrations you will be able to apply to the Holibob commercial team to have the credentials upgraded to allow live bookings. Once updated, all bookings confirmed on the production API will be live, you will be charged and the booking will be confirmed with the supplier.

You will be able to see all bookings within the Extranet when logged in with credentials linked to your partner account. When using Extranet you can switch between viewing sandboxed or live bookings.

There is an additional API endpoint available that is simply an alias against the production API, however, this API will enforce sandbox mode regardless of the state of your account

The sandbox API is available at: https://api.sandbox.holibob.tech/graphql