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

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

 

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.

 

 

 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.

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

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.

Click Save.

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.

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 :

 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.

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

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.

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

 

 

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.