Joomla! Documentation™

Joomla! 

4.0

This page is intended to reflect the Specification of the Joomla Web Services API. This will be updated and reflect the latest version of Joomla at all times

Authentication

There is a group of api-authentication plugins to allow custom authentication into Joomla Core which can have any implementation. We have chosen not to implement a full blown oAuth 2 specification into the core however it is intended that this can be achieved with the plugin group (and by disabling the "API Authentication - Joomla Token" plugin and the "User - Joomla Token" plugin). The built in authentication uses a Bearer Token implementation.

The hmac is the main security feature of our Bearer token implementation. This is the RFC 2104 HMAC of the seed data using Joomla's site secret (the $secret in configuration.php) as the key. The base64 encoded seed is stored in the database in the user profile table of the database.

The token itself is the base64-encoded representation of a string algorithm:user_id:hmac. The algorithm tells us which cryptographic hash function was used to generate the HMAC. Per the security considerations of RFC 6151 we forbid the use of the less secure cryptographic hash functions. In fact, the current implementation only allows SHA-256 and SHA-512 with SHA-256 being the (hardcoded) method used to generate the token displayed to the user. (i.e. SHA-512 is added for forward compatibility).

For security and privacy reasons users can only view their own token, even if they are Super Users. Users with com_users edit privileges can also disable, enable or reset another user's token (if they believe the token has been compromised) BUT they still cannot view it. Users can also choose to disable their own API Key.

There is also a legacy basic authentication plugin for simple local development however this is likely to be removed before the release of Joomla 4.0.0 stable.

Requests

Content Negotiation

Joomla by default will return JSON API Responses when requested with a Accept: application/json header as well as with the specific JSON API header. Joomla will support the ability to add additional content types that can be responded. System plugins adding this mapping will be responsible for ensuring that components support this mapping. Core Joomla will not support additional content types.

Language Negotiation

Currently language negotiation is not supported. However we open to adding support for this in the future.

Routing

Basic Information

Joomla CMS needs to use a separate Router for the API as the API will be strictly RESTful (i.e. a POST and GET request to the same URL will give different outcomes). For this we will therefore use the Joomla Framework router which is already restful and then map requests to it to JInput variables so that similar JInput data is populated to that in the Joomla Web Interfaces.

As Joomla's API lives in the api folder of Joomla all routes will start with /api on the root Joomla URL. This is not customisable unless you decide to rewrite folder locations with a custom includes/defines.php files in all levels of the CMS (do this entirely at your own risk and don't expect much/any support!).

Adding Routes

Routes are registered through plugins with type webservice. A plugin can add one or more routes (each should be aware of it's RESTful type). Whilst puristically 1 plugin per content type would be better, there is also a tradeoff between number of plugins installed on your Joomla site for management. Therefore we recommend a plugin per component to expose admin data and then if you are coding in extra routes an extra plugin (of course this is just a recommendation - use cases of course vary!)

Responses

API Response Format

Joomla evaluated several response API Formats including JSON-LD, JSON API and Collection+JSON. For a more detailed evaluation you can look at this summary document produced as part of our GSOC 2017 project. We have settled on using the JSON API v1.0 specification (at the time of producing the JSON API 1.1 which recently became release candidate had no major libraries implementing it and appeared stuck).

The JSON API v1.0 specification can be found on the json api website.

Some batch interactions in the Joomla API will also use the JSON API Partial Success module for error handling which can be found in this gist.

Richardson Maturity Model and Hypermedia

We expect Joomla to largely comply with Level 3 of the Richardson Maturity Model. If you want to read about what this means we recommend looking at the Fowler page on it. Our entity systems (JTable and JModel) aren't ideally suited for this which means in some places especially around data relations there's likely to be some implementation difficulties.