Joomla version 1, 2 and 3 had no good, universal way of adding a RESTful JSON API to a component. There was a hodgepodge of solutions (ab)using Joomla's routing to essentially end up with a format=json request query parameter post-SEO parsing and some basic logic to convert HTTP verbs into respective Controller tasks, sometimes with rudimentary support for HAL or similar HATEOAS solutions. In plain English: we had no good way to write JSON APIs which didn't suck royally!
Joomla 4 addresses this problem with the introduction of a new
official Joomla application, the API application which lives in the
api folder of your site.
The API application uses a set of plugins in the
webservices group to determine which of the installed
API components will be responding to requests. These plugins are also
responsible for determining the routes (URLs) for the respective
component's JSON API. While having a plugin control whether a particular
component provides an API may sound odd, it makes sense. Depending on
the site, you don't always want to expose everything under the sun in a
JSON API. For example, if you do not have a use case for listing the
extensions over the JSON API it makes more security sense having that
feature unpublished.
Beyond the plugin, your component needs an API part just like it
does for the frontend (site) and the backend (administrator)
applications. The difference is that you only have Controllers, Models
and Views. You do not have view templates. The Views descend from
\Joomla\Component\Banners\Api\View\Banners\JsonapiView
which manages the data conveyed through a
\Joomla\CMS\Document\JsonDocument as a JSON
formatted response.
As for who can access the API… we'll see about that in the next section.