!!! Magazine Articles Draft Section !!!
This section contains articles in preparation of articles in the Joomla Magazin
Web Services API:
Introduction to the 'outside' interface of the Joomla Web Services API
The external API interface of Joomla is actual the way programs or AI may interface the web site addressing web site components. So you may want to know a bit more about it.
Another option for Access is an MCP server (Model Context Protocol) for AI, but that is a different story. By the way, actually Joomla prepares its own included MCP server but there are already a lot of independend sulotions with different purposes out there.
This article intends to introduce you to the general interface, how the URL parts and the response data looks like. It does not contain a list of component endpoints (Which component has which endpoints). You will find links at the end of the article to lists though.
Following is a general introduction to the URL path used when calling Joomla Webservice API functions
URL Uniform Resource Locator Structure (abbreviated):
www.example.com/documentation/index.html?p1=A&p2=B#ressource
\_____________/\_______________________/\________/\________/
| | | |
host path query fragment
Translated into Joomla API form:
example.com/api/index.php/v1/config/application?page[offset]=30&page[limit]=30
\__________/\____________/\___________________/\_____________________________/
| | | |
host api path endpoints query
The 'api path' leads direct into the root web site 'api' folder where the further parameter are collected.
The endpoints are defined by web services plugins of joomla or components
The query parameters aligns to existing code in controller or model
| Api path: | /api/index.php/ | -> webservice starting in web site '/api' folder |
| Endpoints: | v1/config/application | -> routes to address functionality |
| Query: | pagination: | ->page[offset]=30&page[limit]=30 |
| filter: | ->filter[catid]=2&filter[state]=1 | |
| sorting: | ->list[ordering]=created&list[direction]=desc |
Tip: Special characters like '[' and ']' must be converted to '%5B' and '%5D' like in other HTML queries
Endpoints:
v1 /secondhand /books /1/....
\___/ \________/\_____/\______/
| | | |
version compon. section sub sections
| Version | If the API route interface gets a B/C (breaking change) the version number will be increased |
| Component | The component which handles the request |
| Section | The controller/model/table part inside the component which handles the request |
| Sub section | Variable (Id of a table item) or further route definition. Not to be confused with "?..." URL query part. The subsection definition may also be ASCII characters. |
Examples:
- v1/secondhand/books
- v1/secondhand/ books/ 5
- v1/content/articles/1/contenthistory
Calling an Endpoint:
Besides using endpoints in php programms using the curl library a curl command may already exist on your command line (Win 11, macOs, Linux)
cURL (Client URL) is a free and open-source command-line tool used to transfer data to or from a server using a wide range of network protocols.
curl -X GET \
-H "Accept: application/vnd.api+json" \
-H "X-Joomla-Token: YOUR_API_TOKEN" \
"https://example.com/api/index.php/v1/content/articles?
filter%5Bcategory%5D=12&filter%5Bsearch%5D=joomla
&page%5Blimit%5D=5"
The "https://example.com/api ..." part must be written in one line
Typical API route definitions
The commands supports the CRUD (Create, read, update, delete) operations.
The CRUD definitions for table items result in following API routes (example):
| Command | Endpoint | Comment |
|---|---|---|
| GET | v1/secondhand/articles | Lists all articles with content items |
| GET | v1/secondhand/articles/:id | Lists content items of article |
| POST | v1/secondhand/articles | Creates new article with data |
| PATCH | v1/secondhand/articles/:id | Writes parameters into selected article |
| DELETE | v1/secondhand/articles/:id | Deletes selected article |
':id' has to be replaced with the article number
Attention: There is no **PUT** command support in Joomla
Examples:
??? ToDo: Get/patch/delete
Special API route definition (example)
??? Media ...
Special Endpoints:
- media
- custom fields
Custom Field endpoints
api/index.php/v1/fields/content/articles
Custom fields definitions have their own endpoints. These endpoints return the definitions of the fields (name, type, options), not the values stored in articles.
| .../v1/fields/content/articles | List all custom fields defined for articles |
| .../v1/fields/content/articles/7 | Get one custom field by ID |
| .../v1/fields/groups/content/articles | List custom field groups for articles |
| .../v1/fields/groups/content/articles/3 | Get one field group by ID |
POST, PATCH and DELETE commands are supported, so they can be created, changed or deleted
The query part starts with '?'. See above.
The 'functions' used must be supported by the model of the addressed object.
Pagination request
For pagination add
?page[offset]=90&page[limit]=30
| Part | Meaning |
|---|---|
page[limit]=30 |
Number of results per page |
page[offset]=90 |
Starting point, for pagination |
which should be written like
?page%5Boffset%5D=90&page%5Blimit%5D=30
Each '[' and ']' has to be escaped. In curl '-g' (globoff) may be used to avoid this.
Filter request
Depending on your requested object Filter can adress several properties.
For example: 'author', 'category', 'search', 'state', 'featured'
The following requests work on get article ...
?filter[category]=12&filter[state]=1&filter[search]=joomla%20webservices
?filter[category]=12&filter[state]=1&filter[search]=joomla+webservices
?filter[tag][]=3&filter[tag][]=22&filter[tag][]=18&filter[tag]
?filter[search]=content:Magritte
Spaces in search text may be encoded with '%20' or '+'.
Ordering request
The direction is either 'ASC' or 'DESC'
The ordering does need to align to a module field name. Which may include the table abbreviation name
?list[ordering]=a.created&list[direction]=DESC
?list[ordering]=fp.ordering&list[direction]=asc
example that fetches articles from category ID 12 whose title or text matches “joomla”, sorted by newest first and limited to 5 results:
curl -g -X GET \
-H "Accept: application/vnd.api+json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
"https://example.com/api/index.php/v1/content/articles?filter[category]=12&filter[search]=joomla&list[fullordering]=a.created DESC&page[limit]=5&page[offset]=0"The URL broken down
| Part | Meaning |
|---|---|
/api/index.php/v1/content/articles |
Articles endpoint of the Joomla 4/5 Web Services API |
filter[category]=12 |
Only articles in category ID 12 |
filter[search]=joomla |
Free-text search on the article |
list[fullordering]=a.created DESC |
Sort by creation date, newest first |
page[limit]=5 |
Number of results per page |
page[offset]=0 |
Starting point, for pagination |
yyy
-g(globoff): curl otherwise interprets[and]as URL globbing patterns and throws an error. Alternatively, URL-encode them as%5Band%5D:
have to mask the square brackets for filter with backslashes. For example:
curl -H "Authorization: Bearer MY_AUTH_TOKEN" "https://example.org/api/index.php/v1/content/articles?filter\[featured\]=1"
-------
Spaces in search:
In curl '-g (globoff)' may be used to
No. The brackets belong only to the parameter name (filter[search]), not to the value. The value just needs to be URL-encoded, and in curl the whole URL should be in quotes so the shell doesn’t misread it.
Option 1: encode the space yourself
curl -g -H "Accept: application/vnd.api+json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
"https://example.com/api/index.php/v1/content/articles?filter[search]=joomla%20web%20services"+ instead of %20 also works in a query string: filter[search]=joomla+web+services.
Option 2: let curl do the encoding
curl -g -G -H "Accept: application/vnd.api+json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
--data-urlencode "filter[search]=joomla web services" \
"https://example.com/api/index.php/v1/content/articles"Here -G turns the --data-urlencode data into query-string parameters, so you can write the search text with normal spaces. This is the easiest form to read in an article.
Notes
- A raw, unencoded space inside the URL string can cause a 400 error or be cut off, depending on the curl version and server, so don’t rely on it.
- As far as I know, Joomla treats the whole value as one search string rather than splitting it into separate words, so
joomla web serviceslooks for that phrase. I haven’t confirmed this in the docs, so test it on your own installation before stating it in your article.