Joomla 4 – Joomla API
This presentation was done
- Tim Davis – BasicJoomla YouTube Channel | Session in English | 2022.11.23
Present slides https://slides.woluweb.be
video (English)
1. Please contribute
Help improving this presentation that will be converted to a Joomla Community Magazine article:
- if you think of other tips & tricks
- if any information can be more precise
- if you know of any other resource
- if you spot any typo
- if you see any error
- …
then please get back to me! ❤️💙🧡💚
1. How this presentation 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
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
Alexandre Elisé's series of scripts showcasing the Joomla API
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.
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
4. Create, Update, Fetch and Delete Joomla Articles with the API
4.1. Create Joomla Articles with the API
4.1.1. Terminology
Some basic terminology first: When using the Joomla API
- Create =
post
- Update =
patch
- Fetch =
get
4.1.2. See the Articles Manager
This is a fresh website so I see that “No Articles have been created yet”
4.1.3. Prepare the POST script
Create your POST script on your website
- create a new file on your website (for example
api-post.php
at the root) - go to https://github.com/alexandreelise/Manual/blob/patch-1/docs/general-concept/webservices.md
- go to the “Using the PHP cURL Functions” section (because we want here an independent script so we don’t use the Joomla Framework version)
- copy the code for “Define some variables” and paste it in your file
- copy the code for “POST” and paste it at the end of your file
Customize your POST script on your website
- in your file adapt the variable
$url
with your domain name. In my example:- from
$url = 'https://example.org/api/index.php/v1';
- to
$url = 'https://api.joomlacustomfields.org/api/index.php/v1';
- from
- and paste your Token. In my example:
- from
$token = '';
- to
$token = 'c2hhMjU2OjI3NDpmOGMyNGIyMmI4ZTI0YzhlN2VhMGI1YmI2MTk5ODdiODViZWIwYjBhMTkwYzYxMmZkMDEzYWUxNzg5MmE2YzNm';
- from
Good to know: when you Create an article
- instead of using (just like in the database of a Joomla website) the classical
introtext
for the text which comes before the potential READ MORE- and/or
fulltext
for the text which comes after the potential READ MORE
- you can use
articletext
which is “smart” and will separate your text intointrotext
andfulltext
when detecting<hr id="system-readmore">
4.1.4. Execute your script
Simply
- open a new browser tab
- type the full url of your script
- press Enter to open that url
- the script is being excuted
- and finally the page displays some feedback
- this is only to reassure you that everything was fine
- as such, displaying anything is totally unnecessary
- with other words, you could simply comment or delete the line
echo $response;
4.1.5. Go back to or refresh the Articles Manager
Tadam you can see that the Article was indeed created!
4.2. Update Joomla Articles with the API
4.2.1. Prepare the PATCH script
The procedure is totally similar to the one of the previous script:
Create your PATCH script on your website
- create a new file on your website (for example
api-patch.php
at the root) - go to https://github.com/alexandreelise/Manual/blob/patch-1/docs/general-concept/webservices.md
- go to the “Using the PHP cURL Functions” section (because we want here an independent script so we don’t use the Joomla Framework version)
- copy the code for “Define some variables” and paste it in your file
- copy the code for “PATCH” and paste it at the end of your file
Customize your PATCH script on your website
- in your file adapt the variable
$url
with your domain name. In my example:- from
$url = 'https://example.org/api/index.php/v1';
- to
$url = 'https://api.joomlacustomfields.org/api/index.php/v1';
- from
- and paste your Token. In my example:
- from
$token = '';
- to
$token = 'c2hhMjU2OjI3NDpmOGMyNGIyMmI4ZTI0YzhlN2VhMGI1YmI2MTk5ODdiODViZWIwYjBhMTkwYzYxMmZkMDEzYWUxNzg5MmE2YzNm';
- from
Good to know: when you Update an article
- the field
articletext
does not work - you should use (just like in the database of a Joomla website)
introtext
for the text which comes before the potential READ MORE- and/or
fulltext
for the text which comes after the potential READ MORE
4.2.2. Execute your script
Simply execute your script as already explained above.
4.2.3. Go back to or refresh the Articles Manager
When opening the Article, we can indeed check that
- the Title has changed
- as well as the Introtext and Fulltext
4.3. Playing with Custom Fields
Adding a value to some Custom Field of an Article directly in the database using a query in PHPMyAdmin is not so obvious because it involves several Tables which are linked.
But as you will see, adding a value to some Custom Field of an Article via the Joomla API is super easy.
4.3.1. Create a Custom Field
In this example I create a Custom Field of Type “Text”
- its Title is “Temperature”
- its Name (meaning Alias) becomes then automatically “temperature” upon Saving (but I could of course type another Name like “temp” if I wanted)
4.3.2. Adapt the PATCH script
Now I need to edit my api-patch
script as follows
- in the
$data
I add a new line'temperature' => '15 degrees Celcius'
- (and I don’t forget to add
,
at the end of the previous line)
4.3.3. Execute your script
Simply execute your script as already explained above.
You already see on what is displayed that “temperature” is mentioned.
4.3.4. Go back to or refresh the Articles Manager
When opening the Article, we can indeed check that
- the Custom Field “temperature” has been filled in
4.4. Fetch Joomla Articles with the API
A good usecase for this script: an intranet or an app where one wants to display some news (articles) from your Joomla website
4.4.1. Prepare the GET script
Create your GET script on your website
- create a new file on your website (for example
api-get.php
at the root) - go to https://github.com/alexandreelise/Manual/blob/patch-1/docs/general-concept/webservices.md
- go to the “Using the PHP cURL Functions” section (because we want here an independent script so we don’t use the Joomla Framework version)
- copy the code for “Define some variables” and paste it in your file
- copy the code for “GET” and paste it at the end of your file
Customize your GET script on your website
- in your file adapt the variable
$url
with your domain name. In my example:- from
$url = 'https://example.org/api/index.php/v1';
- to
$url = 'https://api.joomlacustomfields.org/api/index.php/v1';
- from
- and paste your Token. In my example:
- from
$token = '';
- to
$token = 'c2hhMjU2OjI3NDpmOGMyNGIyMmI4ZTI0YzhlN2VhMGI1YmI2MTk5ODdiODViZWIwYjBhMTkwYzYxMmZkMDEzYWUxNzg5MmE2YzNm';
- from
4.4.2. Bonus 1: select another Category
In this example, we suppose we want to get all articles from Category 2
Of course, you can easily change the ID of the Category you need by adapting the following line of code:
$categoryId = 2;
4.4.3. Bonus 2: only get Published Articles
What is you only want to get Articles which are Published.
In the database, you probably know that technically being
- Published means that “state” is 1
- Unpublished means that "state is 0
So all we need to change in the script is to change
/content/articles?filter[category]=
into
/content/articles?filter[state]=1&filter[category]=
4.4.4. Execute the script
Simply execute your script as already explained above.
4.5. Delete Joomla Articles with the API
Create your DELETE script on your website
- create a new file on your website (for example
api-delete.php
at the root) - go to https://github.com/alexandreelise/Manual/blob/patch-1/docs/general-concept/webservices.md
- go to the “Using the PHP cURL Functions” section (because we want here an independent script so we don’t use the Joomla Framework version)
- copy the code for “Define some variables” and paste it in your file
- copy the code for “DELETE” and paste it at the end of your file
Customize your DELETE script on your website
- in your file adapt the variable
$url
with your domain name. In my example:- from
$url = 'https://example.org/api/index.php/v1';
- to
$url = 'https://api.joomlacustomfields.org/api/index.php/v1';
- from
- and paste your Token. In my example:
- from
$token = '';
- to
$token = 'c2hhMjU2OjI3NDpmOGMyNGIyMmI4ZTI0YzhlN2VhMGI1YmI2MTk5ODdiODViZWIwYjBhMTkwYzYxMmZkMDEzYWUxNzg5MmE2YzNm';
- from
We don’t provide screenshots here. By now you know how it works!
5. Thank you
Peter Martin for his excellent presentation about the Joomla API which allowed me to finally dive into this topic
Alexandre Elisé for all the interesting chats about the Joomla API a.o. and for taking the time to provide a new script every time I was having a new idea of improvement!
Tim Davis for having me today on his YouTube Channel
So many members of the Joomla Community for being #jPositive
😉
6. Get in touch
Any suggestion about this presentation?
Please feel free to contact me. I’ll be happy to keep improving it 🙂
Marc Dechèvre | woluweb
+32 474 37 13 12 | +32 2 772 58 69