Joomla 4 – Joomla API

by Marc Dechèvre

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

Alexandre Elisé's

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

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.

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';
and paste your Token. In my example:
- from $token = '';
- to $token = 'c2hhMjU2OjI3NDpmOGMyNGIyMmI4ZTI0YzhlN2VhMGI1YmI2MTk5ODdiODViZWIwYjBhMTkwYzYxMmZkMDEzYWUxNzg5MmE2YzNm';

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 into introtext and fulltext 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';
and paste your Token. In my example:
- from $token = '';
- to $token = 'c2hhMjU2OjI3NDpmOGMyNGIyMmI4ZTI0YzhlN2VhMGI1YmI2MTk5ODdiODViZWIwYjBhMTkwYzYxMmZkMDEzYWUxNzg5MmE2YzNm';

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';
and paste your Token. In my example:
- from $token = '';
- to $token = 'c2hhMjU2OjI3NDpmOGMyNGIyMmI4ZTI0YzhlN2VhMGI1YmI2MTk5ODdiODViZWIwYjBhMTkwYzYxMmZkMDEzYWUxNzg5MmE2YzNm';

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';
and paste your Token. In my example:
- from $token = '';
- to $token = 'c2hhMjU2OjI3NDpmOGMyNGIyMmI4ZTI0YzhlN2VhMGI1YmI2MTk5ODdiODViZWIwYjBhMTkwYzYxMmZkMDEzYWUxNzg5MmE2YzNm';

We don’t provide screenshots here. By now you know how it works!

5. How to launch any of the scripts automatically

Given the fact that our scripts here are independent of Joomla

we can put them on our own website
or even on another server (if we trust its owner of course, since being able to see the Token means being a Super User)

Lauching any of the scripts can be simply done:

by opening the corresponding URL in a browser
- either directly
- either for example thanks to a nice button in the backend
by calling this URL in any piece of code (PHP or other)
by setting up a Cron job calling this URL
- either via the tool provided by your host (free)
- either via some online tool providing cron tasks (in general paid)
by setting up a Task Scheduler in Joomla

So obviously it means that you can automate the execution of the creation / update of your Joomla Articles at any time interval.

5.1. Example 1: via a nice button in the backend

In Joomla 4 it has become even easier than before to create a Custom HTML Module in the backend.

Take advantage of this feature to create a nice interface to your Users.

5.2. Example 2: via Joomla Task Scheduler

The Task Scheduler is a new feature introduced with Joomla 4.

Go to System > Schedule Tasks
Click on the New button
Create a Task of Type “GET Request”
Configure it (put an absolute link for “Request URL”. Example: https://www.MYDOMAINNAME.com/api-blabla.php)

6. Be the only one who can run your scripts

If somebody know that you have a script called for example api-test.php, this person could flood your websites with request on that url.

A typical way to avoir that is on Apache servers is to create a htpsswd, meaning you have to

add a few lines in your .htaccess
add a .htpsswd file, to which your .htaccess lines will refer with the correct path (for exemple /YOUR_PATH/public_html/.htpasswd)

When a htpsswd is enabled, you get a popup asking for the defined username & password before accessing.

You can typically

either use your Host tools to generate such an .htaccess rule
or use an online generator (like https://hostingcanada.org/htpasswd-generator)

But we need to be more specific because

we only want to block our scripts, not our whole website.
we only want to block our scripts if they are launched in the browser, not if they are launched by the website itself
- either via some code
- either via the Task Scheduler

Let us first show a good example of such an .htaccess rule:

<FilesMatch "^api*">
AuthType Basic
AuthBasicProvider file
AuthUserFile /YOUR_PATH/public_html/.htpasswd
AuthName secure
<RequireAny>
Require valid-user
Require ip 127.0.0.1 185.221.181.208
</RequireAny>
</FilesMatch>

6.1. How did restrict the rule to our scripts

Let’s suppose that all my scripts filenames start with api.

Then I want to have this htpsswd popup asking only for the files starting with api.

This is why in the snippet of .htaccess below we have <FilesMatch "^api*">

6.2. How did we allow the scripts if launched by the website itself

See the line Require ip 127.0.0.1 185.221.181.208

127.0.0.1 corresponds to the localhost. In some cases it is enough
in my case though, when launching my script with Joomla’s Task Scheduler, my script was blocked: I also had to allow explicitely the IP of my server
- Q: So how did I find the IP address of my server?
- A: Simply by checking the IP address given for “A Record” for my Domain Name, with any online tool like https://www.ns-lookup.io/

6.3. More information

For more information about this kind of .htaccess rules, see https://httpd.apache.org/docs/2.4/upgrading.html

7. Using the Joomla API to Import and Update Articles directly from a Google Sheet

Being able to POST or PATCH a single Article programmatically with a few lines of code thanks to the API as shown above is great… but the added value in real life is quite limited at this point.

Indeed, having to prepare 1 script to create only 1 article would seem quite cumbersome. But once you can do it for 1, one starts to think “what about having a loop to create multiple articles” :)

When I first spoke about this with Alexandre, I would already have been happy to do it with a CSV file:

export to CSV-format from an Spreasheet
and then select that file with a kind of import button somewhere

But Alexandre went further:

why bother exporting/importing a CSV file: if you use Google Sheet for example, you can share it with a simple link… to its CSV version
why importing Articles only into 1 website: let’s have a column in our Google Sheet to select for each row in which website we want to create the corresponding Article
why limit the import to the native Fields, let’s make it easy to also import (any number of) Custom Fields
why not allow to also have json in a cell since the following Fields are stored in json-format in the database
- Intro Image & Full Image links, together with their configurations (Description, classes, …)
- Urla, Urlb, Urlc
- Custom Fields of type Subform
why having to respect some order of the columns in the Google Sheet: let’s allow the user to have any order

7.1. Create Custom Fields in Joomla

This step is not necessary of course: it only applies if you intend to use the script to import Custom Fields values

Let’s suppose we create a website for a Rock band. It would be much easier for the musicians to add their new concerts simply in a Google Sheets than to lean how to use a CMS.

Those concerts would then be imported and/or updated in the website

either on demand by opening a link to the script (which can be in the form of a nice button in Joomla’s backend btw)
either at regular intervals (hours/days/weeks/months, whatever)
- via a regular Cron job
- or using Joomla’s Task Scheduler

7.2. Prepare Google Sheets

7.4. Prepare Google Sheets script

See https://github.com/alexandreelise/j4x-api-examples/blob/master/using-raw-php/smart-add-edit-to-multiple-sites-from-csv-url.php

8. Using the Joomla API to Import and Update Articles directly from AirTable

You have probably already heard of AirTable: https://airtable.com/

If not, let’s simplify it by saying that it is a big like a Google Sheet but really more powerful:

its goal is not to make calculations
since it is a real online database

In practice, more and more companies/associations are moving their data to Airtable so that they are interconnected and no more in silos.

8.1. Prepare Airtable

After creating a table in Airtable and before using it in our script, we need to make that table publicly available with the Airtable API

Coming soon

8.2. Prepare your Airtable script

See https://github.com/alexandreelise/j4x-api-examples/blob/master/using-raw-php/smart-add-edit-to-multiple-sites-airtable-api.php

Breaking news: now support for adding multiple downloaded and cached images as attachments

Coming soon

8.3. –

Coming soon

9. GraphQL API together with the Joomla API

Add or Edit Joomla! Articles Via API To Multiple Sites Chosen Randomly in from a predefined list Using Github GraphQL API

9.1. Prepare your OMDb script

See https://github.com/alexandreelise/j4x-api-examples/blob/master/using-raw-php/smart-add-edit-random-defined-sites-github-graphql.php

Coming soon

9.2. –

Coming soon

10. OMDb API together with the Joomla API

Note: OMDb is a Movie database

Turn your top 5 favorite movies into Joomla Articles thanks to OMDb API and Joomla API

Coming soon

10.1. Prepare your OMDb script

See https://github.com/alexandreelise/j4x-api-examples/blob/master/using-raw-php/turn-your-top-5-favorite-movies-into-joomla-articles-omdb-api.php

Coming soon

10.2. –

Coming soon

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

😉

12. Get in touch

https://slides.woluweb.be

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

https://www.woluweb.be/contact

https://www.slideshare.net/woluweb

Joomla 4 – Joomla API

1. Please contribute

1. How this presentation came to life

2. Resources

3. How to get the Joomla API Token

3.1. Create a new User

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

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

4.1.2. See the Articles Manager

4.1.3. Prepare the POST script

4.1.4. Execute your script

4.1.5. Go back to or refresh the Articles Manager

4.2. Update Joomla Articles with the API

4.2.1. Prepare the PATCH script

4.2.2. Execute your script

4.2.3. Go back to or refresh the Articles Manager

4.3. Playing with Custom Fields

4.3.1. Create a Custom Field

4.3.2. Adapt the PATCH script

4.3.3. Execute your script

4.3.4. Go back to or refresh the Articles Manager

4.4. Fetch Joomla Articles with the API

4.4.1. Prepare the GET script

4.4.2. Bonus 1: select another Category

4.4.3. Bonus 2: only get Published Articles

4.4.4. Execute the script

4.5. Delete Joomla Articles with the API

5. How to launch any of the scripts automatically

5.1. Example 1: via a nice button in the backend

5.2. Example 2: via Joomla Task Scheduler

6. Be the only one who can run your scripts

6.1. How did restrict the rule to our scripts

6.2. How did we allow the scripts if launched by the website itself

6.3. More information

7. Using the Joomla API to Import and Update Articles directly from a Google Sheet

7.1. Create Custom Fields in Joomla

7.2. Prepare Google Sheets

7.3. Share Google Sheets

7.4. Prepare Google Sheets script

8. Using the Joomla API to Import and Update Articles directly from AirTable

8.1. Prepare Airtable

8.2. Prepare your Airtable script

8.3. –

9. GraphQL API together with the Joomla API

9.1. Prepare your OMDb script

9.2. –

10. OMDb API together with the Joomla API

10.1. Prepare your OMDb script

10.2. –

11. Thank you

12. Get in touch