Playing with the Joomla Web Services (API) - part 1

The Joomla API is a very interesting topic because it is so powerful.

But there is much to tell so I propose to start a new series of articles.

At the end of this series of articles, you will be able to import your Articles together with their Custom Fields to your Joomla website directly from a Google Sheet thanks to the Joomla API !

The program will be as follows:

JCM March 2023

1. How this presentation came to life
2. Resources
3. How to get the Joomla API Token

JCM April 2023

4. Create, Update, Fetch and Delete Joomla Articles with the API

JCM May 2023

5. How to launch any of the scripts automatically
6. Be the only one who can run your scripts
7. Change the API Token if needed

JCM June 2023

8. Using the Joomla API to Import and Update Articles directly from a Google Sheet
9. Troubleshooting
10. Final tip

1. How this article came to life

There have already been several presentations about the Joomla API.

They were certainly interesting (showing Postman, explaining how you can create a Smartphone App exchanging with your Joomla website, …) but I was always a bit frustrated because :

the target of these session was more developers or people who are already play with APIs
there was never a basic example or a step-by-step procedure allowing to “lower the threshold”

This changed on 23 September 2022 where I had the chance to be present at JoomlaDay D-A-CH (gathering several german-speaking countries, namely Germany – Austria – Switzerland). In particular Peter Martin gave an excellent “How to use APIs in your Joomla website?” (see links hereafter): At the end of his session, Peter would give a few little PHP scripts showing how to create or update Articles.

I asked to Peter whether he could share his scripts. He did even better: there is a new official website Joomla! Programmers Documentation with a page about Web Services and Peter made a Pull Request on Github to add the examples (see hereafter).

Coming back to Belgium, I was really excited to play with these examples.

Then I contacted Alexandre Elisé from Martinique, who is very passionate about the Joomla API and we elaborated on these examples. Indeed

I had ideas of real usecases for the Joomla API
and Alexandre had the coding skills to bring those ideas to life

So after several iterations over a few weeks, we ended up with a series of “little” scripts. The goal was indeed

to give a flavour of what Joomla API can bring
to provide short and easy-to-customize scripts (I like to say “one-page scripts” since in practice they have only about 200 to 300 lines)
to have scripts which are independent
- note though that they could be easily adapted to use the Joomla Framework… but then it would become an installable extension and this goes beyond the scope of this initiation
- the advantage of an independent script is that it can even run on another server, be triggered by a cron task (from your server Panel… or from the native Joomla Task Scheduler introduced in Joomla 4 as well)

So a long story short: this presentation aims at allowing a maximum of people to start using the Joomla API, which offers a strong competitive advantage compared to other CMS for example.

2. Resources

Peter Martin – “How to use APIs in your Joomla website?” at JoomlaDay D-A-CH on 2022.11.23

Alexandre Elisé

Alexandre’s blog: https://apiadept.com/blog-joomla-specialist
API collection for Postman: https://github.com/alexandreelise/j4x-api-collection
Series of scripts showcasing the Joomla API: https://github.com/alexandreelise/j4x-api-examples

When you go to https://github.com/alexandreelise/j4x-api-examples please click on the Star button if you appreciate Alexandre’s scripts & contribution :

Joomla! Programmers Documentation (in construction)

https://manual.joomla.org/docs/general-concept/webservices
Peter Martin’s PR: https://github.com/joomla/Manual/pull/41/commits/647588e4f90ee692b731cb468a3037eff4df24c1
Alexandre Elisé's improvement on that: https://github.com/alexandreelise/Manual/blob/patch-1/docs/general-concept/webservices.md

Joomla! Documentation

Adding an API to a Joomla Component https://docs.joomla.org/J4.x:Adding_an_API_to_a_Joomla_Component

3. How to get the Joomla API Token

Before using the Joomla API (and any of the scripts below) we need a Joomla API Token.

At the moment, the Joomla API Token can only be generated for Super Users.

So be sure to keep it secret because any person having somehow access to that Token is de facto a Super User and can do everything on your website, including deleting everything.

Note: as far as I know, it is the idea at some point to allow non Super Users to access the API (which is necessary if you want to give a Token to a third-party who only wants to fetch data for example).

[EDIT] On 2022.11.25 Alexandre shares this additional information on Facebook:
“You don’t need to be a Super User to access the Joomla Api. You can create a Web Services usergroup for example, go to Global Configuration and give this Group Permissions for API and site login to be able to see the token. You need also to add the Web Services group you just created to the list of allowed groups in the token user plugin config. But for now you still cannot have fine-grained ACL and Access Level per endpoint.For more security you could also disable sensitive webservices plugins like the users web services plugin but then the consumer app using the token cannot manage user info. I haven’t tried it yet, but I think if you give specific permissions to the Web Services usergroup then add only app user in this group you could achieve want you want even if it’s still not per route / endpoint.”
“Just did a quick test on a fresh joomla 4.2.5 install you don’t need to be Super User. morever Joomla seems to already handle permissions per endpoint but only for core endpoints. At least that’s what I’ve tried. that means that if you create for example a web services group to manage all consumers of your Joomla web services and then deny create patch delete users for this usergroup the app/consumer of the joomla web services will get a 403 Forbidden http status code when trying to perform denied actions.”
Joomla Api Without Super User > Demo video (18 min)

3.1. Create a new User

Actually you could of course create a Joomla API Token for your own account.

But it is probably a good practice to create a distinct user

you can then for example disable at any time
you can then see easily in the User Actions Logs who has done what and when (and see whether it was the API or yourself)

3.2. Give a strong password

3.3. Assign to the User Group Super User

3.4. Go the Joomla API Token tab and Read

3.5. Save

Now that you have saved the User, the Joomla API Token has been created… but for security reasons only that given user can see it (nobody else, not even other Super Users).