JSON API

Overview

Akeeba Release System integrates with the Joomla! API application. For an introduction to the API please take a look at the Joomla Community Magazine article on the Joomla API Application and the Joomla API Specification.

We contributed the “User - Joomla Token” authentication method to Joomla for secure authentication to the Joomla API using a token.

The ARS JSON API allows you to automate software releases on your site. It's very strongly recommended that you use, or at least take a look at the code of, the Akeeba Release Maker application as the canonical implementation of an API consumer for software release automation.

Like all Joomla API endpoints, the ARS endpoints support the following HTTP verbs:

• GET Lists a record or a collection of records.
• POST Create a new record.
• PATCH Modify an existing record.
• DELETE Delete a record. Note that this is a destructive, irreversible operation!

Using a bare endpoint, e.g. v1/ars/categories, is only possible with GET to get a list of items or POST to create a new record.

Using an endpoint followed by a record's numeric id, e.g. v1/ars/categories/123, operates on the specific record. Therefore you can use it with GET to read the specific record, PATH to modify the record or DELETE to delete the record.

The fields returned match the database table fields. GETting a list of records will include additional fields, typically giving you the human readable title of the language, access level, category and release of a record as applicable.

Important notice about PATCH requests. Joomla expects you to send the full record data in each PATCH request. You CAN NOT just send the fields you want to modify. Furthermore and against the JSON API standard, Joomla does NOT return the new state of the record. You will need to do a GET request to determine whether the record has been updated. These have already been reported as bugs and will likely be resolved in a future release of Joomla.

Super User access required. The Joomla API application is currently only available for Super Users only. This means that you need to provide the Joomla Token of an enabled Super User account to work with the API. As a result we have not been able to do a whole lot of access control tests with the API application implementation. Should the Joomla API application start supporting other user groups we will need to perform further tests to ensure that the access controls in the API application integration of Akeeba Releases System match those used in the HTML (Site and Administrator) Joomla applications.

Categories

Endpoint: v1/ars/categories

Manage the ARS Categories

URL parameters (optional):

• search String. Filter by a partial match to their title or description.
• published Integer (0/1). Filter by published or unpublished status.
• show_unauth_links Integer (0/1). Filter by Show Unauthorized Links status.
• supported Integer (0/1). Filter by The Software Is Still Supported status.
• access Integer or array of integers. Filter by items accessible by any of the provided Joomla access levels.
• language String. Filter by the specific language code (* means “All languages”).

Releases

Endpoint: v1/ars/releases

Manage the ARS Releases

URL parameters (optional):

• search String. Filter by a partial match to the release's version or description. Use the form version:1.2.3 to only list the releases matching the version number (in this example 1.2.3) exactly. The difference is that without the version: prefix something like 1.2.3 would also match 11.2.3, 1.2.30 and 1.2.3.a1.
• category_id Integer. Filter by releases belonging to the specified Category given the Category's numeric ID.
• published Integer (0/1). Filter by published or unpublished status.
• maturity String (stable, rc, beta, alpha). Filter by releases matching the specific maturity.
• minMaturity String (stable, rc, beta, alpha). Filter by releases whose maturity is the given string or something more stable. For example, giving beta will match releases with beta, rc and stable maturity.
• show_unauth_links Integer (0/1). Filter by Show Unauthorized Links status.
• access Integer or array of integers. Filter by items accessible by any of the provided Joomla access levels.
• language String. Filter by the specific language code (* means “All languages”).
• latest Integer (0/1). Only show the latest releases in each category. Use this by itself or with category_id but NOT any other filters. In any other case the results are unpredictable!

Items

Endpoint: v1/ars/items

Manage the ARS Items

URL parameters (optional):

• search String. Filter by a partial match to the item's title or description. Use the form file:something to only match items with their type set to file and their filename's basename matching exactly something. Use the form url:something to only match items with their type set to link and their URL's basename matching exactly something.
• category_id Integer. Filter by items belonging to the specified Category given the Category's numeric ID.
• release_id Integer. Filter by items belonging to the specified Release given the Release's numeric ID.
• published Integer (0/1). Filter by published or unpublished status.
• show_unauth_links Integer (0/1). Filter by Show Unauthorized Links status.
• access Integer or array of integers. Filter by items accessible by any of the provided Joomla access levels.
• language String. Filter by the specific language code (* means “All languages”).