1. You are here:  
  2. Home
  3. Developer's Guide
  4. Jomres API
  5. REST API & Webhook case study

This manual is being depreciated. Much of the information here is out of date.

The new Jomres Documentation, updated in 2022, can be found at Jomres.net/documentation.

REST API & Webhook case study 

Requires Jomres 9.8.25 or later

Introduction

Here I will describe how the REST API and Webhooks can be used together to build a web service.

This functionality is very ambitious, to date I'm not aware of any other self hosted booking portal for either Joomla or Wordpress that includes it. It sets Jomres apart from it's competitors because it offers features that, until now, could only be enjoyed by the big SaaS booking businesses.

Both features saw considerable development in the second half of 2016, and as is always the way, development outpaces documentation. As a result, I will describe a case study of how these features can be used. First however I need to introduce you to the features, describe what they're intended for and any pertinent information I feel you'll need.

Webhooks and the REST API should be considered two sides of the same coin.

  • The REST API is designed to facillitate the ability of remote services to request data from, and update data to, a Jomres installation. This is achieved through a secure Oauth2 token based system that's tied to individual property managers. This allows individual managers to grant access to their own properties to remote services.
  • The Webhooks feature is designed to offer a framework that, again, a manager can configure to send notifications to remote services that they determine. Webhook notifications are small snippets of data, the payload normally only contains a handful of IDs of affected database rows. To query the complete change, the remote service would need to send a callback to the REST API on the server.

This all sounds very complicated, so let's simplify it somewhat

  • REST API receives stuff.
  • Webhooks sends stuff.

Security

I will not go into great detail here about security as it's discussed elsewhere in the manual. The important point to note is that Webhook configurations are assigned to property managers, not property uids. This is worth remembering as previous plugins in Jomres were tied to specific properties, but these features are instead linked to manager ids. This means that Webhook authentication is checked against the property manager/property uids cross reference table.

In Jomres, Super Property Managers are not typically given access to individual properties, instead they're automatically given access to all properties. Super Property Managers therefore usually don't have a record in the cross reference table for a given property. As a result, if a Super Manager creates a webhook then that webhook might not be triggered. 

When working with the Webhooks, make sure that the user creating Webhooks is a "normal" property manager.

To clarify this, the current version of the Webhooks feature doesn't offer the Webhook configuration option in the menu to Super Property Managers.

REST API features are semi-restricted, it depends on the feature. For example, in this case study we'll use the API Features Webhooks plugin to answer callbacks from a remote service that's been notified of a change to a property in Jomres. That particular plugin checks to ensure that the manager who created the REST API keys has access to the properties being called, however there's a API Feature called "Search" which is a super property manager only API feature and isn't tied to any specific properties. That particular feature, however doesn't offer any POST functionality, it's purely a search mechanism.

Discussion

One thing I've learned over the years of working on Jomres is that not everybody wants everything on offer. For this feature some people will only want the REST API framework then they'll develop their own code to make use of that framework, others want everything handed to them on a plate, and others want to selectively choose what to use.

As a result, the REST API/Webhook framework has been designed to be modular, deferring to related plugins to provide the bulk of their functionality.

Both frameworks require installation of the API Core and Webhooks Core respectively.

  • REST API Core allows property managers to create API key pairs which will authorise remote services to access their property data. The Oauth2 authentication is bundled in Jomres itself, and doesn't need to be installed. This was done to ensure that enpoints would always be predictable and clean.
  • Webhooks Core allows property managers to create Webhook implementations, and actually triggers webhook notifications. Every webhook needs an authentication method, three are currently available : None, Basic and OAuth. These allow basic notification to remote services, however you're not limited to these methods. It's entirely possible that you might want to create your own implementation method, for example if your site's users predominently use Home Away then you might want to build an integration with the Home Away API. This is why the Webhooks Core is only responsible for creating Webhooks and their configuration options, and triggering webhook integration scripts.

 

As previously mentioned, many of our users are developers who use Jomres as a foundation that they can use to build their own unique sites. They're skilled programmers in their own rights and Jomres is just a building block on the path to that goal. We encourage this and much of the functionality available should be considered as "sample" code on how to do things the right way in Jomres. The REST API/Webhook functionality is no different. Let's be honest, there are so many different PMSs and Channel Managers out there, it's impossible for us to write integrations for all of them, so it's my philosophy that it's better to give developers the tools to achieve those integrations in the minimum amount of time possible.

Basic Webhook/REST API setup

In this case study we will show you how to setup an installation of Jomres to send Webhook notifications and allow a remote server to respond to those calls.

You will need to install the REST API Core, API Feature Webhooks ( which is designed as a companion to the Webhooks feature, but can be used by any authorised remote service ) and the Webhooks Core plugins.

If you're using this feature for the first time and are just experimenting then you'll probably benefit from visiting our Public Snippets repository on Github and downloading the Simulation Webhook Responder.  This simulation code is designed to receive a notification from Jomres, then to call Jomres' REST API back to request the full details of the change. In reality remote services would selectively decide if the API Feature Webhooks endpoints are the relevant endpoints to call in the event of the notification, depending on their own particular setups, but for education purposes this is how we'll do it here.

In my installation of WAMP Jomres resides in /www/joomla_portal/ so I'm going to copy the directory contents of simulation_webhook_responder into /www/simulation_webhook_responder This set of scripts will act as a receiver of Webhook calls, and automatically trigger calls back to the Jomres REST API to find out the details of the change that it was notified about.

In practice, the webhook responder would in fact be a remote service, such as a Property Management System's gateway or a Channel Manager's API. As it's impossible to predict how the data will actually be used by the far end, we're going to just receive calls and send them back to Jomres API to confirm that everything's working as expected.

All this stuff happens out of sight of a user so it can be tricky to track what's happening. To monitor what the webhook responder is doing I use a syslog application for Windows called "Visual Syslog Server for Windows". If you have your own tool for monitoring syslogs use that, or Visual Syslog. We'll get to configuration for connecting to it in a moment.

Jomres Installation

For the purposes of this case study I'm going to assume that you're running the Joomla Portal Quickstart, as that's the most likely setup that will be used. You can do this on one of the other flavours of Jomres Quickstart, it doesn't need to be one of the Quickstarts either, any Jomres installation will do. Screenshots here however will be from the Quickstart Portal.

In this article I will assume that you're reasonably familiar with Jomres. I'll show you relevant screenshots so that you can ensure that you're following the steps as described, but on the whole you shouldn't struggle too much.

First visit the Jomres Plugin Manager and install the API Core, Api Feature Webhooks, Webhooks Core and Webhooks Authmethod None plugins.

 

Now go to Site Configuration and configure it so that the webhooks and API menu options are available through the frontend.

 

Next, create a new user in the Joomla ( or Wordpress ) user manager. I'll create mine and call them "manager".

 

 

 I'll use the Jomres user manager to make them a property manager, and give them access to Fawlty Towers and Best West Hotel ( property uids 1 & 2 respectively ).

Now that you've done this, you should see some new options under the Account menu option in the frontend manager's toolbar :

 App Key Management is the link that you use to access the REST API configuration page where API keys are created. Webhooks is the link for Webhook configuration. We'll start off by creating an API key pair.

Click on App Key Management and click New. The Client ID and Secret are created for you. Make sure that you click the checkbox next to "Get data as part of a webhook communication", as this gives the App client rights to use the API Webhook Feature's functionality.

 Save the key pair, and again in the Accounts menu click Webhooks and click New. Set the URL to http://localhost/simulation_webhook_responder/ and click Save.

 

Responder setup

You're almost ready to start testing, but first we need to configure the responder script. Go into the simulation_webhook_responder directory in your WAMP/XAMPP/MAMP/LAMP public_html directory and open config.php.

Assuming you've installed Visual Syslog, then you can probably leave the settings for that alone. In the Client ID and Secret fields, copy and paste the Client ID and Secret from the App Key Management -> Edit page into this document. The responder will need to know these details so that it can send requests back to the Jomres installation to pull the full details of the changed record.

The trailing slash in the server's url is important, don't forget it.

Save the document and close it.

Testing

At this point we could start testing, but that would mean performing a lot of activities to trigger the webhook code built into Jomres. Fortunately, we don't need to do this, we can artificially trigger webhooks. Go back to our Github repository for the responder, and there you'll see a file called j00005fake_webhook_calls.class.php We can use this file to trigger webhook calls to happen every time a Jomres page is loaded.

Copy this file into your /jomres/remote_plugins/custom_code directory ( create the directory if it doesn't already exist ) and rebuild the registry. From now on, until you delete this file it'll run every time a Jomres page is loaded.

Open it in your editor and you'll see lots of ids. Here you'll need to do some of your own legwork, as every system is likely to be different. You'll need to identify contract ( booking ) uids, invoice uids etc as they exist on your own installation.

 

 Once you've modified this file and added your own Ids, then scroll down further, you'll see a variety webhook triggers. Make sure they're all commented out, then uncomment

$webhook_event = 'booking_modified';
$webhook_data = array ( "property_uid" => $property_uid, "contract_uid" => $contract_uid );

When you next visit any page in Jomres ( e.g. the Dashboard ) the webhook notification should appear in Visual Syslog and look something like this. Double click the last line to see the popup which will contain the actual details of the response. You do not need to be logged in as a manager for this to happen.

 

 

 

What happened?

  1. First the j00005fake_webhook_calls.class.php script created a fake webhook call that would normally be triggered if a contract was modified by a manager.
  2. Next the Webhooks Core plugin used the Webhook integration to send a message to http://localhost/simulation_webhook_responder/ to tell it that the booking has been modified.
  3. The index.php in http://localhost/simulation_webhook_responder/ called the Jomres API back, specifically the endpoint http://localhost/joomla_portal/jomres/api/webhooks/1/booking_modified/41 to request the updated details of the booking ( contract ).
  4. When it received a response, it sent the contents of the response to Visual Syslog for you to analyse.

 

You can now go ahead and comment this section, and uncomment others in j00005fake_webhook_calls.class.php to continue testing.

 

Postscript

Why is this a good thing?

This functionality is the foundation of a new way of working with Jomres. As the Internet of Things evolves so applications like Jomres need to evolve to keep pace. Allowing remote services to interact automatically with Jomres without going through a web browser makes Jomres accessible to an uncountable variety of outside devices and services, anything from Channel Manager services to mobile apps to Property Management Systems, CRM systems and other things we haven't even thought of yet.

 

Jomres and you, forging ahead into the future together.

 

 

Back to Jomres.net