PhpStorm HTTP Client collection for the Joomla 6 Web Services API.
The collection has a request for every route of the OpenAPI specification of the Joomla Web Services API, with the example request bodies of the specification. It works in PhpStorm and in any other JetBrains IDE with the built-in HTTP Client.
- Install Joomla 6 on your server or local development environment or use an existing Joomla 6 website.
- Login into the Joomla 6 administrator panel and go to the Global Configuration.
- On the Site tab make sure that the Search Engine Friendly URLs option is enabled. If it isn't, enable it and click the Save & Close button at the top.
- Click on the User Menu button at the top right and select Edit Account.
- On the User Profile page go to the Joomla API Token tab.
- Check if the token is present, if it isn't, click the Save button at the top and the token will be generated.
- Close the Edit profile page.
- Go to System > Plugins.
- Click on the Filter Options button. In the Select Type dropdown choose webservices.
- Make sure all Web Services plugins are enabled. If any of them is disabled, enable it and click the Save & Close button at the top.
Your Joomla website is now ready to be used with the webservices API and the PhpStorm collection.
There are two ways to get the collection:
- A release: each release since 6.2.1 has the file
joomla-ws-api-<version>-phpstorm.zip, the collection of that version of the specification. Unzip it. - The
phpstormbranch: thephpstormbranch always has the collection of the newest specification, also with improvements that are not released yet. Clone it, or download it as a zip file:git clone --branch phpstorm --single-branch https://github.com/joomla-projects/API-Endpoints.git joomla-phpstorm
Copy the folder with all its contents into a project you open in PhpStorm, or open the folder itself as a project.
The folder contains one .http file per group of endpoints (a tag in the specification), for example banners.http
and content-articles.http.
The requests use two variables: base_url and api_key. They are set in two environment files in the folder of the
collection.
- Open
http-client.env.jsonand change the value ofbase_urlto the URL of your Joomla website, for examplehttps://www.myjoomlawebsite.com/api/index.php. Keep the/api/index.phppart at the end of the URL, as that is the endpoint for Joomla API requests. - Copy
http-client.private.env.json.exampletohttp-client.private.env.json. - Copy the API token from your Joomla user profile and paste it as the value of
api_keyinhttp-client.private.env.json.
The private environment file is listed in .gitignore, so your token is not committed by accident.
The requests in joomla-update.http do not use the API token. They use the token of the Joomla Automated Updates
service, which you find in the options of Joomla Update. Set it as the value of update_token in
http-client.private.env.json if you want to use these requests.
A simple test to see if the API endpoints are working is a GET on Config Application.
- Open
config-application.http. - In the toolbar at the top of the editor, select the joomla environment in the Run with dropdown.
- Click the green run icon in the gutter next to Get Global Configuration. The URL for this request is
{{base_url}}/v1/config/application. - If all is working you should see a response with status 200 in the Services tool window, with the global configuration of your Joomla website in JSON format.
Requests that work on a single item use a variable in the URL, for example {{article_id}}. These variables are
defined at the top of each .http file with a default value:
@article_id = 1
First, retrieve a list of articles.
- Open
content-articles.http. - Run the request List Articles. The URL for this request is
{{base_url}}/v1/content/articles. - If your Joomla website has articles, you should see a response with status 200 and a list of articles in JSON format.
Retrieve an article with a specific ID.
- In the JSON result of the content/articles request, find the ID of an article you want to retrieve. An example ID is shown as
"id": 11. - Change the variable at the top of
content-articles.httpto@article_id = 11. - Run the request Get Article. The URL for this request is
{{base_url}}/v1/content/articles/{{article_id}}.
List requests support paging, and some also support filters. The available query parameters are listed in a comment above the request. Add them to the URL, for example:
# Optional query parameters: page[offset], page[limit], filter[search], filter[state]
GET {{base_url}}/v1/content/articles?filter[search]=joomla&page[limit]=5
The .http files are generated from the specification by
scripts/generate-phpstorm.mjs.
Do not change them by hand: to improve a request, change the specification in a pull request to the main branch of
joomla-projects/API-Endpoints. After the merge, the phpstorm branch is updated
automatically.
To generate the collection yourself, from a clone of the main branch (Node.js 22 or later):
npm run phpstorm # writes the collection in dist/phpstorm/