Joomla Api Specification
From Joomla! Documentation
This page is intended to reflect the Specification of the Joomla API. This will be updated and reflect the latest version of Joomla at all times
There is a group of api-authentication plugins. Core Joomla currently just has a basic authentication as the focus was on building the architecture for the project. We are hoping to move to a token based system before the release of Joomla 4.0.0 stable.
Joomla by default will return JSON API Responses when requested with a
Accepts: 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.
Currently language negotiation is not supported. However we open to adding support for this in the future.
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!)
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!)
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 API 1.1 was not created and recently became release candidate and no major libraries implemented it).
The JSON API v1.0 specification can be found on 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 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. Whilst our entity systems (JTable and JModel) aren't ideally suited for this which likely means some short term pain as we bed this in.