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.
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.
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 .