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
- https://dach.joomladay.org/programm-2022/programm-samstag-2022/how-to-use-apis-in-your-joomla-website
- https://www.youtube.com/watch?v=AXytRiEkjVc
- https://petermartin.nl/en/presentations/joomla/how-to-use-apis-in-your-joomla-website
- https://slides.db8.nl/md/22-joomla4-api.html
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).
3.6. Log in as the new User and copy the Token
Some articles published on the Joomla Community Magazine represent the personal opinion or experience of the Author on the specific topic and might not be aligned to the official position of the Joomla Project
By accepting you will be accessing a service provided by a third-party external to https://magazine.joomla.org/
Comments 1
Something bothers me about the title. More specifically, the term 'API' in the title. This seems to be the most abused term lately when referring to Joomla!'s Web Service a.k.a. REST API. The Joomla! API includes a lot more than just Web Service support. So I find using just the term API rather confusing. But maybe that's just me, since even respected colleagues seem confused when I refer to the Joomla! API, apparently thinking I'm talking about the Web services API.
Other than that a cool article