How to use the API plugin
From Jomres v4 manual
Contents |
Introduction
The API remote server handling is designed to allow a remote server to communicate with the Jomres installation on http://www.domain.com/ and, if it has the API key of a property, to query and occupy rooms on said server.
It is anticipated that the API handling would be used by an intermediate to advanced PHP developer. It isn't designed to be plugged into any existing systems, instead it's expected that a developer would build upon the API framework to produce their own solution.
To use the API you must first use the Jomres plugin manager to install the API plugin. Once that's done then the software to receive and process API calls is put onto your server. You'll still need to set up a remote server to send these calls to your local server.
Currently API handling goes from remote to local (jomres) server. There isn't a framework for local to remote server. Depending on demand, this may change.
Demo
The remote server demo can be found at http://remote.jomres-demo.net/
The demo connects with a Jomres demo server test property called "remote testing" to enable users to play around with the basic functionality of the API handling. The scripts are very simple and are designed to demonstrate how it is possible to send a query to a Jomres server and receive an XML response. They don't demonstrate how they would be used in a real world scenario, as each scenario is different but if you're looking to build some remote server -> jomres server communication then they're a good base to work from.
Security
Property and User handling is authorised by the validation of API Keys. It is recommended that you use SSL links to communicate from remote to local (Jomres) server.
If a remote server should try to communicate with a local (Jomres) server but supplies an invalid key then the failure is logged. After a number of failures the remote server is then blocked from communicating with the local server for a specific amount of time. The number of times and the amount if time is defined in the jomres_API_transaction class, method jomres_API_check_for_failures.
If a server is blocked, it is possible to remove the more recently blocked transactions via the API Transaction list to re-enable access.
API keys
User API keys are only available via the administrator's area. Property API keys are available via the Frontend Property Manager's menu -> Tariffs and Rooms -> Property tab.
API keys come in two flavours: "property" and "user". There are no example scripts for User API handling, but there are several examples of Property API handling.
- Query a room's (by room number) price, no time period specified.
- Query a room's (by room number) avaiability, time period specified.
- Occupy a room (by room number) by time period.
It should be noted that unlike in Jomres, where stays are by arrival to departure dates, time periods (yyyy/mm/dd - yyyy/mm/dd) in the API delineate the first and last nights so if you book yyyy/03/01 to yyyy/03/03 then the room will be booked for the nights of the 1st, 2nd and 3rd. In Jomres if the arrival and departure dates are set to the same, then the room is occupied only on the 1st and 2nd.
Management
On installation of the API plugin one new table is created, which is a history of all API transactions. This list of transactions can be viewed by using the newly visible API Transactions button in the Site Administrator's control panel of Jomres.
From this page you can view the status of the transactions, including any possible security issues, see a raw output and delete a transaction.
