Jomres logo
Postman logo

I've noticed recently quite a view visits to the old manual's Using Postman article page.

That page is old, Postman's UI has changed considerably so I decided that it was time to create a new tutorial for how you can use Postman to access the Jomres REST API.

Let's start with the most basic of questions : What is Postman used for?

Postman is an excellent tool that developers can use to access REST API endpoints of applications. You can download a copy of it from here. It's free. I use it a lot when creating new endpoints.

Jomres has a whole ton of REST API endpoints. You can see them here. Some of them don't require authentication, however many do, therefore if you want to interrogate your Jomres installation using the API (perhaps for generating statistics automatically) then you'll first need to learn how to connect to secure endpoints. Postman is extremely popular for this, and developing/testing endpoints in general.

Getting started

In this tutorial I'm going to show you how to pull your favourite properties from data stored in the database so firstly make sure you've clicked the Heart icon next to some properties in the search results pages so that you've got some properties saved (you need to be logged in when you favourite those properties).

Next, you'll need first to go to the Jomres Plugin Manager and install the Favourites endpoint plugin.

Go to the plugin manager and in the tabs at the top, click on Core API Plugins

postman tutorial 03

Scroll down to the plugin called "Api Feature Favourites" and click to install it.

postman tutorial 04

 

The REST API functionality is available to any registered and logged in user, though of course property management features (called Scopes) are limited to property managers. If you don't want guests accessing the API Key management page, you can use the Access Control plugin to limit their ability to use that page.

In the following screenshot you can see the Dashboard of my Jomres installation. The API Key Management feature is available underneath the Account Details menu option. If you can't see it, it's possible that it's been switched off in Site Configuration > Misc tab, or in Access Control.

  postman tutorial 01

 

 When I click on it, I can see a list of existing API Keys. In this screenshot there's already one key, which is automatically created by the Messaging System. We will ignore it as we want a new key specifically for accessing the user's favourites.

postman tutorial 02

Click on the New button on that page and you'll be taken to the new client id and secret pair page.

postman tutorial 05

Give the Client ID and Secret pair a name. I've called it "Get/Set favourites".

Scroll down to the bottom and you'll find the permissions section. Allow the pair to both Get and Set favourites. In this tutorial we'll only use the Get functionality.

postman tutorial 05 scopes

Click Save.

postman tutorial 06

Once you have saved the key pair, you're ready to use them. Click View to view the new keypair.

 In this page, you'll see the Authorisation URL. You'll need it in a moment.

postman tutorial 07

Setting up Postman

Open up Postman. If you haven't used it before, don't be overwhelmed.

Postman has things called Workspaces. In here you create collections of API requests and information. Create a new Collection called "Postman Demo".

Right click the Collection name and click Add Request. You don't need to name it if you don't want to. Underneath that you'll see a field GET Enter Request URL

Use the Authorisation URL from the previous selection, and complete it by adding favourites on the end, so that it looks something like this :

http://localhost/Joomla_4/jomres/api/favourites

 Remember, your request url will probably be different to mine. If you have // somewhere in the url, take it out otherwise the API will respond with a 404 response.

If you want, you can click Send. If you do, you'll get a 401 response like this :

postman tutorial 10

 You can't access this particular endpoint without sending a valid token as part of the request, so let's setup Postman to do that now.

Click on the name of the Collection, and in the Authorization tab in the main panel you'll need to change the Type to OAuth2

When you do that, you'll be able to use the Client ID and Secret you created a moment ago to get an Access Token.

First of all, give the token a name, I called mine "Postman demo token".

Next set the Grant Type to Client Credentials.

Set the Access Token URL to the Authorisation URL from the Jomres page (without changing the URL) and fill in the Client ID and Secret too.

postman tutorial 08

 Once you've done all that click the Get New Access Token button to get the token from your Jomres installation. Assuming that all goes well you'll see a success message.

In the Collections column at the side you're now ready to setup the authorisation for the endpoint. Click on New Request (or if you've renamed it, whatever you named the request to), and underneath where it says

GET http://localhost/Joomla_4/jomres/api/favourites

You'll see a set of tabs. Click on the tab marked "Authorization".

postman tutorial 12

By default the Type is set to "Inherit from parent". In my copy of Postman this doesn't always work, so instead I prefer to change that to OAuth2 and on the right where it says "Available Tokens" I select the newly created "Postman demo token". Leave the Header Prefix to Bearer.

postman tutorial 09

Now, when I click the Send button to send the request, this is what I get in return from my Jomres installation

postman tutorial 13

 

 

Wrapping Up

That's it for this tutorial. I won't go into any more depth here, you've had enough torture for now.

You now know how to install an API Endpoint plugin, create an API Key pair, how to request a token, and how to send a request to the REST API.

Remember to look at the the API documentation at https://api.jomres.net/ to get an idea of some of the different endpoints available. 99% of them require an endpoint plugin. Most of them also require an access token, but not all.

Now, go and have a coffee or a beer, you've earned it.

 

REST API

  • 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 released as a commercial project. Since then Jomres has become the world's oldest online booking plugin for any PHP CMS. It has been used in Joomla 1.0, 1.5, 2.5, 3 & 4 and WordPress 4, 5 & 6.

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