Extending the Joomla Web Services API

A component cannot add routes by itself, because the API router is shared by every extension and is built before any component is loaded. The plugin is the hook. It also means the routes exist only while the plugin is enabled: disabling plg_webservices_tallpine in System → Manage → Plugins removes every Tallpine endpoint at once, which is a useful switch during an incident. The core webservices plugins (plg_webservices_content, plg_webservices_banners and the rest) work the same way, and a fresh installation enables them.

The plugin extends CMSPlugin and implements SubscriberInterface. It subscribes to onBeforeApiRoute, whose argument is a BeforeApiRouteEvent (added in Joomla 5.0). The event carries one argument, the ApiRouter, and getRouter() returns it.

Source: joomla-cms 6.2-dev: the Banners webservices plugin, and Joomla Manual: How plugins work

The class is final, as the core plugin classes are. getSubscribedEvents() returns the mapping from event name to method name, and the method declares the concrete event class as its parameter type. The plugin needs neither the application nor the database, so it uses no Aware trait.

A Joomla 4.4 and later plugin is built by a service provider, exactly as the content plugin on Plugin development and events. The provider differs only in the group, the element and the class name.

Source: joomla-cms 6.2-dev: the Banners plugin provider and manifest

In the package pkg_tallpine the plugin is listed after the component with <file type="plugin" group="webservices" id="tallpine">plg_webservices_tallpine.zip</file>, as shown in Extension types, manifests and packaging. Check System → Manage → Plugins after the first installation: a disabled webservices plugin is the most common reason for an endpoint that answers 404.

ApiRouter::createCRUDRoutes($baseName, $controller, $defaults = [], $publicGets = false) builds five Route objects and adds them to the router. With the arguments used above, the router receives:

The second argument is the controller name, not a class. The router splits the string trails.displayList at the dot: trails becomes the request’s controller and displayList its task. The defaults array becomes the route’s default variables. Two keys have a meaning for the application:

Every other key is copied to the request as an input variable. That is how the categories route passes extension=com_tallpine to com_categories, whose controllers use it to select the category tree. An id is captured from the URL and put in the same place, which is why controllers read it with $this->input->get('id', 0, 'int').

Anything that does not fit the five CRUD shapes is a Joomla\Router\Route passed to addRoutes(). The constructor takes the list of HTTP methods, the pattern, the controller string (name.task), the regular-expression rules for each :variable of the pattern, and the defaults:

Source: joomla-cms 6.2-dev: createContentHistoryRoutes() in the Banners plugin

Four rules follow from how the router matches.

After routing, the application checks the request’s Accept header against application/vnd.api+json, or against the format list of the route if one was set in its defaults. If nothing matches, the API answers 406 Not Acceptable. A client that sends Accept: application/json therefore fails on the standard routes; this is a frequent surprise and is covered in The Web Services API.

The API part has its own folder in the extension zip and its own <api> element in the manifest. The installer copies it to api/components/com_tallpine in the web root, and the <namespace path="src"> declaration already maps the Api segment of the namespace to it.

Source: Joomla Manual: Manifest files. The core folders for comparison are listed in joomla-cms 6.2-dev: api/components.

There is no services folder, no tmpl folder and, in the core components, no model or table: the API reuses the administrator part. The Tallpine\Component\Tallpine\Api\Controller namespace is found because the MVCFactory resolves class names from the namespace prefix plus the client name (see Namespaces, autoloading and dependency injection).

Inside the API application the component’s MVCFactory is wrapped in ApiMVCFactory. When code asks it for a model or a table, it first looks in the Api namespace and, if nothing is there, silently falls back to the Administrator namespace. This is why TrailModel and TrailsModel written for the administrator screens are enough for the API. It also has a consequence: a bug or a missing check in the administrator model is reachable over HTTP. The model is the right place for validation and for filtering, because it is the only code that all clients share. The note on validation in the administrator MVC page applies with extra force.

The core dispatcher classes for the API are not part of the component either. The core API components contain no Dispatcher class; the application runs Joomla\CMS\Dispatcher\ApiDispatcher, which, unlike the administrator dispatcher, performs no core.manage check of its own. It reads the task (displayList, add, openTrails) from the request, builds the controller named by the route in the Api namespace and executes the task.

An API controller extends ApiController. Two properties tell the base class what the controller serves: $contentType (the plural resource name, used as the JSON:API type, the default model name, and in the singular for asset names) and $default_view. The base class provides the five CRUD tasks, so a minimal controller is only those two properties. The Tallpine controller adds filters and a custom task:

Source: joomla-cms 6.2-dev: the Banners API controller and the Articles API controller

What the base class does, and what that means for an extension author:

A custom task such as openTrails() is an ordinary public method. It must produce the response itself, normally by setting model state and calling displayList() or displayItem(). A task that returns without rendering gives an empty response.

The controller only sets state. The administrator TrailsModel must read it in getListQuery(), with bound parameters and with the viewing access levels of the current user, because the base controller’s read tasks do not call authorise() themselves:

Source: Joomla Manual: Selecting data and the pattern described in ACL in Joomla extensions

The query builder rules, including why bind() takes a variable by reference, are in Database API.

The class must be called JsonapiView, because the view name is built from the document type of the API application (jsonapi). It extends Joomla\CMS\MVC\View\JsonApiView and declares two arrays: the attributes rendered for one item and for each item of a list. The lists are separate because a list should be cheap and an item can carry everything.

Source: joomla-cms 6.2-dev: the Banners JsonapiView and the JsonApiView base class

Things worth knowing about the base class:

Before building a document, the view dispatches onApiGetFields with an OnGetApiFields event holding the field list and the context (the content type). A plugin can call addFields() and addRelations() on the event to add attributes or relationships, and the serialiser dispatches onGetApiAttributes and onGetApiRelation in the same way. That is the route other extensions use to add data to your resources without editing your view, and the route you use to add data to core resources from plg_webservices_tallpine or another plugin. The events are listed in the Manual’s plugin events index; the exact payload classes live in libraries/src/MVC/View/Event and libraries/src/Serializer/Events in the source tree.

Two points deserve emphasis.

Reads are not authorised by the base controller. In the 6.2 source, displayList() and displayItem() apply no authorise() call; an authenticated API user passes the route checks and the rest is decided by what the model returns. The core models filter by viewing access level and state, and so must TrailsModel, as shown above. The Tallpine member-only trail conditions (the Trail Warden access level of Users, groups, access levels and ACL) are protected over the API only if the query uses getAuthorisedViewLevels(). A reader token from the editor group does not see Trail Warden rows, and a guest on the public route sees only rows with the Public level.

The asset name the controller checks must match your access.xml and your table. allowEdit() builds com_tallpine.trail.7 from the option, the singular of the content type and the id. The asset is written by TrailTable, as explained in ACL in Joomla extensions. If the table stores its rows under another asset name (for example com_tallpine.trails.7), the API check finds no rule and falls back to the parent chain, so permissions set on the item appear to have no effect. Override allowEdit() in the controller if the names differ.

Give the front end its own account rather than a Super User token. A group API Reader with core.login.api and no other privilege fits a public map; a group API Trail Editor with core.login.api, core.manage, core.create, core.edit and core.edit.state on com_tallpine fits an importer. The token is generated in the user’s profile once the token plugin is enabled and the user’s group may log in to the API. Joomla stores a seed and derives the token from it, so the token is shown once and cannot be read back from the database. Treat it as a password: keep it in the environment or in the secret store of the front end, and rotate it by regenerating it. The wider hardening of the API (rate limits at the proxy, CORS, disabling Basic Auth) is on Security hardening, MFA and passkeys.