A holidaymaker CMS can provide data to your own web surface. This data has its own structures in JSON format and can be parsed, stored, and cached on your system for rendering.
When data is changed on holidaymaker the lastChange time for that entity will then be updated, and can be requested on its own so your own systems can check to see if it required new data or not.
There are a choice of two flows which are normally followed when requesting this data :
1. Two step request
This system means you could regularly check if data has changed, and if so do a secondary request to fetch it, and store the new last change time. Doing this simple time check means you could check as often as every 5 minutes comfortably, and keep your data up-to-date, and only invalidate your own caches when required.
2. Single periodic request
This system means you would always request the full data and replace it on yours system regardless of the data age. You can do this periodically, but due to the size, and processing scale of the request, we recommend this would be a minimum of 60 minutes. For data which is less up-to-date this can be a much larger delay if required.
To access our data provider API you will be supplied with an endpoint, and both a Client Key and a Client Secret. The key is sent on each request, and the secret is used on each end to create a hash to compare. Your Client Key will also be associated with a set of functions based on your needs.
All of the requests will be to the same endpoint as a HTTP POST using a built request/form string as the body. How your achieve this can be up-to-you as long as the correct authentication hash is sent with each request. We have some boilerplate examples if your front end website is powered by WordPress here. The examples in this article are written in a none-specific language to simply explain the requests.
Endpoint : https://urltoholidaymakerinstall/wp-json/holidaymaker/data
This call does not require full authentication, but simply programatically returns what functions your client key has access too.
Return – Success
Single JSON object with the following properties
Return – Error
If an error is detected then instead you will receive a single JSON object with the following properties
// Url : https://urltoholidaymakerinstall/wp-json/holidaymaker/data
// POST Body : f=me&key=xyzxyzxyzxyzxyz
{
"key": "xyzxyzxyzxyzxyz",
"functions": [
"getAllEvents",
"ageAllEvents",
"getOffers",
"ageOffers",
"me"
]
}All other functions require authentication. This is in the form of sending your client key, a timestamp to be checked, and a MD5 hash generated using all of the parameters concatenated with your client secret. This is then built again on the API side, and checked against your supplied hash.
Return – Success on ‘age’ requests
Single JSON object with the following properties
Return – Success on ‘get’ requests
The responses of these are documented in detail in our entity specification :
Return – Error
If an error is detected then instead you will receive a single JSON object with the following properties
// Url : https://urltoholidaymakerinstall/wp-json/holidaymaker/data
// POST Body : f=ageOffers&key=xyzxyzxyzxyzxyz&c=2024-06-10 12:00:00&a=e2ce059dbf68dfd9716c1df4aa9b2704
{
"lastChange": 1718013259
}
// Url : https://urltoholidaymakerinstall/wp-json/holidaymaker/data
// POST Body : f=getOffers&key=xyzxyzxyzxyzxyz&c=2024-06-10 12:00:00&a=564377fa402bfa1f799af0353a3373ee
{
"offers": [
{
//Offer 1
},
{
//Offer 2
}
],
"categories": [
{
//Category 1
},
{
//Category 2
}
],
"lastChange": 1718013259
}This hash is created using your client key, a lowercased version of the function, the check timestamp, and your client secret.
These are all concatenated together using the ‘|‘ (pipe) character and then hashed using MD5.
Example:
clientkey|functionlowercase|checktimestamp|clientsecret
eg xyzxyzxyzxyzxyz|ageoffers|2024-06-10 12:00:00|abcabcabcabcabc
This would produce e2ce059dbf68dfd9716c1df4aa9b2704
/*------*/
const CLIENT_KEY = "xyzxyzxyzxyzxyz";
const CLIENT_SECRET = "abcabcabcabcabc";
/*------*/
function getPostArguments(functionName) {
var checkTime = "2024-06-10 12:00:00"; //Get current timestamp using language date formatting
var hash = md5(CLIENT_KEY + "|" + functionName.toLowerCase() + "|" + checkTime + "|" + CLIENT_SECRET);
//If needed as key/value array
var paramsAsArray = {
f: functionName,
c: checkTime,
a: hash,
key: CLIENT_KEY
};
//or return as query string
return "f=" + functionName + "&c=" + checkTime + "&a=" + hash + "&key=" + CLIENT_KEY;
}All Image Url Strings attached to entities in our data are sent as a full size image url (to the max width of 3000px). These could be very large and unsuitable for responsive and mobile-centric web rendering.
Our surface rendering have access to an image engine to process and resolve appropriately sized images based on screen density and width – we would recommend using a similar system in your implementations of our data provider API.
All images have usage rights defined by our client, so if your system needs to download raw versions of these images to then process and resolve differently, please let us know so we can make any changes needed to our client’s SLAs and/or privacy documents.
In some circumstances we would be able to provide and instance of our image engine hosted, and maintained by us, with a different endpoint and code examples of how to convert the urls to the engine urls – however this would required expanded SLA with our client and yourselves, and potential cost.