Introduction to the Jomres Booking Engine REST API

In this article I want to introduce you to some of the Jomres Booking Engine REST API's functionality, specifically functionality that doesn't require an API key or token.

api screenshot

Why?

In today's interconnected world it's not enough to have a website.

CMSs such as WordPress and Joomla are evolving towards being "headless" systems where the CMS is literally just where the content is stored and the frontend, the presentation layer, can be another entirely different technology. Jomres itself is also evolving in the same way. The gateway to this evolution is the Booking Engine REST API in Jomres.

Introduction

The complete REST API documentation can be found here https://api.jomres.net/

Jomres has a large number of Booking Engine REST API endpoints. These endpoints allow remote services to perform certain actions on your Jomres installation, such as add/remove properties, perform searches and more. To access these endpoints you will first need to install the appropriate API Feature plugin. This is done through the Jomres plugin manager, Core API plugins tab.

api plugin manager

 

Almost all endpoints in Jomres require a plugin, however there are two exceptions to this rule. The GET Core Report and the GET Core Properties endpoints. These are pre-installed on all Jomres installations.

The main reason for this is so that the system internally can test that the Booking Engine REST API functionality is working as intended. Some cheap hosting services are not setup to allow this kind of functionality, therefore it's necessary for the system to check that it can work before it will try to use endpoints.

If you click on these links your browser will open a new window with the contents of the API response. You can also use a development tool like Postman (which I use).

http://wordpress-portal.jomres.net/jomres/api/core/report/

http://wordpress-portal.jomres.net/jomres/api/core/get_properties/

All API responses are in JSON format.

In case you're wondering, it doesn't matter if you're using Joomla or WordPress, the endpoints and their responses are the same. Here's the same Core Report from the Joomla demo :

http://joomla-portal.jomres.net/jomres/api/core/report/

Why do I need to know about endpoints?

You might not initially, if you're using Jomres just as an online booking engine. As time goes by, however, your needs will almost certainly evolve. You might decide that you want to build a mobile application for your site, or you might have different servers that want to pull information from, and put information into, your Jomres installation (for example, a PMS on a client's site). To do that you'll need a tried, tested and well documentated REST API so that servers and apps can talk to each other in a language they understand.

Ok, I'm sold, but it doesn't sound very secure

The most common, well understood standard for authentication on the web today is OAuth2, and that's what Jomres uses when permitting access to it's REST API endpoints. To allow a remote service to use an endpoint the Property Manager needs to (don't worry, it's super simple to do) create an API key pair, with a set of permissions that it's allowed to use . The property manager gives that Client ID and secret to the remote service and then the remote service can access the permitted endpoints after asking for an access token.

What happens if I call an endpoint that requires an access token and I don't have one?

Go ahead and find out. Click the following link to try to get a list of guests from the WordPress demo server :

http://wordpress-portal.jomres.net/jomres/api/guests/1/list

As you see, you'll get a response telling you that the authentication information is missing. You can try the same query in Postman, and you'll get the same response. Without a valid access token you'll be (politely) told to go away.

The huge majority of endpoints in Jomres require authentication via an access token, however there are some that do not.

Why are there exceptions?

Because sometimes you want to allow a remote server to access your Jomres site without forcing them to register on your service. The get_properties endpoint above is an example of that. All of the information returned by that endpoint is already publicly available information that can be determined by scraping your site.

Another exception to this rule is the up-coming Jomres New Booking Engine. The NBE API will allow remote servers or user interfaces to make valid bookings on your site via the REST API. Again, use of an access token isn't appropriate in this instance because it's just an evolution of the existing booking functionality which already doesn't demand access tokens.

Endpoints in Jomres that don't require authentication via a valid token are internally called auth-free endpoints. These expose information that, as I said before, is already publicly available on your website so they don't expose any sensitive information. Instead they package up that information in such a way that a remote service can use to drive guests to your site to make bookings.

Ok, so what are these other exceptions?

Let me give you several examples. The endpoints given here are provided by the Search and Site Structure API Feature plugins.

This first set of endpoints provide remote services with information about your site's setup. Clicking on these links in your browser will open up a new window with the data returned in JSON format. Normally a remote service will use this information to build their own queries to search for specific properties, the links here are provided to help you to visualise the kind of information that is returned by an endpoint.

http://wordpress-portal.jomres.net/jomres/api/site_structure/room_types
http://wordpress-portal.jomres.net/jomres/api/site_structure/property_types
http://wordpress-portal.jomres.net/jomres/api/site_structure/property_features
http://wordpress-portal.jomres.net/jomres/api/site_structure/property_features_categories
http://wordpress-portal.jomres.net/jomres/api/site_structure/regions
http://wordpress-portal.jomres.net/jomres/api/site_structure/countries
http://wordpress-portal.jomres.net/jomres/api/site_structure/categories

The next set are provided by the API Feature Search plugin.

http://wordpress-portal.jomres.net/jomres/api/search/stars/3
http://wordpress-portal.jomres.net/jomres/api/search/dates/2023-06-09/2023-06-12
http://wordpress-portal.jomres.net/jomres/api/search/price/100/120
http://wordpress-portal.jomres.net/jomres/api/search/features/3
http://wordpress-portal.jomres.net/jomres/api/search/towns/Buriram
http://wordpress-portal.jomres.net/jomres/api/search/regions/3450
http://wordpress-portal.jomres.net/jomres/api/search/countries/ES

Here I have hard coded search parameters such as the price or property feature id into the url however typically the remote service is more likely to use the information from the Site Structure response to build the endpoints it calls.

Depending on your evolving needs an enterprising developer can use these endpoints on a remote application to pull information from your site to, ultimately, make bookings that you receive on your server.

The NBE functionality is the logical conclusion of that process. If you click this link you will see an error referring to the session id because the booking API requires a unique key added to headers to identify individual bookings, but in principle it's also an exception to the token rule, I.E it doesn't need one.

http://wordpress-portal.jomres.net/jomres/api/booking/initialise/1/en-GB

You can already install and use the NBE plugins on your site, I'll be doing an article on that soon. Check out the API docs for information on the plugins you'll need to install.

Wrapping up

I hope that this article has been informative for you. It's goal has been to introduce you to functionality that's available to your website that you may be unaware of. The Jomres Booking Engine's REST API functionality is powerful and complete, yet it is constantly evolving to meet newly discovered needs of Jomres users.

If you're using the Jomres API and find that there's something missing that you want, please do let me know.

 

 

 

 

 

 

 

 

 

  • Created on .

ABOUT US

vince picDeveloped and maintained by Vince Wooll, Jomres was initially conceived in early 2005 as a Mambo based solution to a client’s hotel management needs. While it wasn't originally expected to be an online booking system it quickly morphed into one as users requested more and more features.

As the number of feature requests grew Vince knew that he would need to dedicate more time to the project and in July 2005 Jomres was formally released as a commercial project. Since then, Jomres has become one of Mambo’s, and now Joomla’s, longest running projects. It has survived various versions of Mambo, then Joomla 1.0, 1.5, 1.6, 1.7, 2.5 and 3.

Aladar joined the project in 2010 after using Jomres for his own projects. He was active on the forum, helping other members of the community and eventually Vince invited him to join the team. Between 2010 and 2018 he was an integral part of the project and made many significant contributions.

Whilst not formally part of the Jomres project, Rodrigo Rocco and Vince have become firm friends. Rod is a freelancer who specialises in doing custom work for Jomres users and developing custom plugins for the system that take advantage of it's modular design. He has built many useful extensions including his fabulous Valentina Template Override Package.

Jomres and the Jomres Logo is trademarked and can't be used without written consent from the owner.

www.jomres.net is not affiliated with or endorsed by the Joomla! Project, Open Source Matters or the WordPress project. The Joomla! & WordPress names and logos are used under a limited license granted by Open Source Matters and the WordPress Projects.

© Copyright 2005 - 2022 Vince Wooll