Joomla Web Services API 101 - Tokens, Testing and a Taste Test

Among the new features for Joomla 4 is the Web Services API. The Web Services API gives you a cleaner way to let your website talk to other websites via APIs. The flexibility this will bring to Joomla websites is only going to be limited by your imagination.

• Use the Web Services API to share articles and content between various websites in a network. You might for example be a website implementer, and you could create your own custom help pages to push out using the Web Services API to all your client sites.
• You could use the Web Services API to connect your website to a third party data source, such as a Business Directory with it’s own API, and then use the Joomla Web Services API to populate your articles from the directory’s API.
• You could use the Web Services API to manage banner advertising on your website network, and integrate reporting and invoicing from Joomla directly into Xero using the Web Services API for both systems.
• If data distribution’s your thing you could use the Web Services API to be the datasource for a headless CMS.
• At JandBeyond this year, Carlos Cámara’s presentation included Web Services. Part of his session was a demonstration on how you can use Joomla 4 Web Services API and Flutter to create mobile applications.
• Thinking further outside the box, you could use the Web Services API to manage a range of IoT devices. A simple example is that when someone submits an article to your website, you could set your internet connected light to change colours.
• The London Joomla User Group did a very in depth walk through for their June meeting. You can watch their Code Along Workshop on YouTube (the link cues it up to the start of the workshop) where they demonstrate how you can push and pull articles between a Joomla 3 and a Joomla 4 website. 

In this article we’re going to walk you through a few key tips on what you need to know about setting things up in Joomla 4 in order to use the Web Services API.

Our article series will continue every second month into 2021 to look at some more detailed examples of how you can use the Joomla Web Services API. If you have ideas for articles on ways you’re using the Web Services API, we’d love to write about this so please get in touch.

Web Services API Endpoints

The list of the Joomla Core APIs endpoints covers all the major core features of Joomla. As you scroll through the endpoints you can see how you can create API calls to leverage your Joomla data and return information in various ways.

Every URL requires authentication unless designated a public URL. For security in Joomla 4.0.0 the default Api Application requires a Super User Joomla API Token (as the API Application is brand new). This may get relaxed as the API stabilizes and is well tested in the community.

The new webservices plugin type also will allow developers to extend their extensions to also be available via the Joomla 4 Web Services API. An example on how that’s able to be done using the Weblinks component is in the Joomla Docs here.

Super User Joomla API Token

The Joomla 4 Web Services API will evolve as Joomla 4 matures, but at the moment access is limited to integration using Super User accounts.

To get your Joomla API Token to be able to use the Web Services API

• Log into your Joomla 4 Administration backend
• Go to the User Menu (top right of screen)
• Select Edit Account
• Click on the Joomla API Token tab

Here you can copy your token, as well as enable or disable the token and reset it if you need to revoke access and generate a new token. Note that if you did choose to reset your token, anywhere that you’ve used that token will no longer work until you update the token to the new value.

You can also edit your token via Users > Manage. Though you cannot see the token for users other than yourself, you can still enable, disable or reset their token. e.g. when there is a suspicion their token has leaked to unauthorised persons.

To set up Postman in the next part of this article, you’ll need your Joomla API Token, so you may like to copy it now, or keep the tab open to come back to when setting up the authentication in Postman.

Testing Web Service API Endpoints

In a practical implementation, API endpoints are usually called at the server level using CURL or are embedded into other programming calls. But when building a web service enabled tool, it’s nice to be able to start off testing that the data you’re expecting to see is the information that’s actually being pulled by the API request.

To test the Web Services API endpoints you can use a range of tools.

• CURL will let you test the API calls using a command line.
• You can also use tools like PHP Storm that allow you to test RESTful Web Services.
• There’s also a tool called Postman available that is specifically designed to test APIs.

Postman is the tool we’re going to show you how to use today, made easier by Alexandre Elise’s work on compiling the Postman Collection of Joomla 4 API Endpoints on GitHub. This handy JSON file covers all of the current Endpoints and will grow over time as more become available.

• The first thing you’ll need is to download and install Postman.
• Next you need to download the Postman Collection of Joomla 4 API Endpoints from GitHub, where there’s instructions on the steps you need to follow on importing the collection to Postman.
• Once you’ve installed the collection, edit the settings and paste in your Joomla API Token on the Authorization tab.
• Next go to the Variables tab and update the base_path variable to point to your Joomla 4 website.
• Finally, use one of the GET endpoints to test that your endpoints are connecting to your site.

If you get a valid result, you’re ready to start building your own queries in Postman to test the API! If you receive a Forbidden error message, you might need to check your settings further, particularly the API Token in the Authorisation tab which needs to have the Key value set to X-Joomla-Token.

Taste Test

So now that you’ve got Postman configured, there’s several layers to the Web Services API. We’re not going to go into learning Postman in depth here, they have a Learning Center to help you with that.

With RESTful Services like the Joomla Web Services API, there’s 5 types of HTTP methods typically used when running commands. Here are some examples of how you might use each method.

POST - Use to create a new record using the destination endpoint

• Create a new article or category using the API
• Create a new banner ad when a record is created in an advertising management tool
• Create a new template style
• Create a new user on the site

For POST methods to work effectively, you need to also provide a JSON string containing the information you want to post into the database. This will be the focus of a future JCM article.

GET - Get data from the Joomla site using a specific endpoint

• Query a list of articles from the website
• Query a specific article from a website
• Query a list of tags being used on the website
• Query a list of redirects on the site
• Adding variables to queries you can focus down the endpoint requests to filter for a specific record. For example adding a value to replace {{article_id}} in an endpoint for articles will allow you to return just the information for a single article as opposed to the entire list of articles.

GET methods are the easiest to test in Postman as they’re retrieving data from the endpoints, and you can then see the JSON data for the returned result in Postman.

PUT - Put data back into an endpoint

PUT methods are destructive, in that they update the record in the database by replacing it with a new record. Currently, the Joomla 4 Web Services API does not have any PUT endpoints, preferring instead to use PATCH which is used to update and modify records.

PATCH - Modify data via an endpoint

• Patch a Banner record to change the finished publishing date or publishing state when the advertising management tool needs to stop and ad from running temporarily.
• Patch a User’s record to update their ACL dynamically when they have changed roles in a company from their HR system.
• Patch menu items to modify their attributes
• Patch language overrides to customise seasonal greetings to visitors to your website

PATCH endpoints are more flexible than PUT endpoints. For PUT, the entire record needs to be rewritten to the database, whereas with a PATCH endpoint, you can update just the specific fields in a record.

DELETE - Delete data using an endpoint

• Delete a contact when they leave the company
• Delete a language override when it’s no longer required
• Delete a template style
• Delete a tag you no longer require

DELETE endpoints are clearly ones that you need to use with caution, as they delete data from your database! If you instead want to move an article to the trash, use the PATCH endpoint instead.

So with those 5 HTTP Methods in mind, you can now take a look through the 111 available endpoints (at the time of publication) and see which ones you can use for your own projects. If you come up with something clever, comment below and perhaps we can share what you’ve done with the new Joomla 4 Web Services API in a future Joomla Community Magazine article.

Resources

If you’re looking at getting started sooner, here’s a range of resources to help you:

• Joomla! API Documentation
• Joomla 4 API Collection - Alexandre Elise
• JoomDev - Joomla 4 API Introduction (November 2019)
• Joomla API Code Along Workshop - Joomla User Group London - June 2020
• Using Joomla API & Google Flutter to build mobile apps - Carlos Cámara - JandBeyond May 2020