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