Adding an API to a Joomla Component

From Joomla! Documentation

Revision as of 04:45, 22 August 2019 by Samoylov (talk | contribs)

This page is intended to document how to integrate the API layer introduced in Joomla 4.0 into your existing Joomla component. This assumes that you are using the default Joomla MVC layer

API integration for Joomla components using the Joomla weblinks extension as an example

Repository: https://github.com/joomla-extensions/weblinks

Pull request: https://github.com/joomla-extensions/weblinks/pull/407

First step[edit]

1. Create a folder src/api

File system structure

2. Create a class WeblinksController

use Joomla\CMS\MVC\Controller\ApiController;

class WeblinksController extends ApiController 
    protected $contentType = 'weblinks';

    protected $default_view = 'weblinks';

Override the following fields:

$contentType - will be used as default for $modelName as well when outputting response as type object
$default_view - will be used as default for $viewName

3. Create a class JsonapiView.php

use Joomla\CMS\MVC\View\JsonApiView as BaseApiView;

class JsonapiView extends BaseApiView
    protected $fieldsToRenderItem = [

    protected $fieldsToRenderList = [

Override the following fields:

$fieldsToRenderItem - array of fields to display a single object
$fieldsToRenderList - array of fields for listing objects

Second step[edit]

1. Create a folder plugins/webservices/weblinks

File system structure

2. In the weblinks.php, create the class PlgWebservicesWeblinks

use Joomla\CMS\Plugin\CMSPlugin;
use Joomla\CMS\Router\ApiRouter;

class PlgWebservicesWeblinks extends CMSPlugin
    public function onBeforeApiRoute(&$router)
        $router->createCRUDRoutes('v1/weblinks', 'weblinks', ['component' => 'com_weblinks']);

In the onBeforeApiRoute method, register all the routes that we need for webservice.

3. Create weblinks.xml

<?xml version="1.0" encoding="utf-8"?>
<extension version="3.1" type="plugin" group="webservices" method="upgrade">
    <author>Joomla! Project</author>
    <creationDate>August 2017</creationDate>
    <copyright>(C) 2005 - 2019 Open Source Matters. All rights reserved.</copyright>
    <license>GNU General Public License version 2 or later; see LICENSE.txt</license>
    <languages folder="administrator/language">

4. Create files en-GB/en-GB.plg_webservices_weblinks.ini, en-GB/en-GB.plg_webservices_weblinks.sys.ini with next content:

; Joomla! Project
; Copyright (C) 2005 - 2019 Open Source Matters. All rights reserved.
; License GNU General Public License version 2 or later; see LICENSE.txt, see LICENSE.php
; Note : All ini files need to be saved as UTF-8

PLG_WEBSERVICES_WEBLINKS="Web Services - Weblinks"
PLG_WEBSERVICES_WEBLINKS_XML_DESCRIPTION="Used to add weblinks routes to the API for your website."

Third step[edit]

1. In the file src/administrator/components/com_weblinks/weblinks.xml add a description for the API files

    <files folder="api/components/com_weblinks">

2. In the file src/administrator/manifests/packages/pkg_weblinks.xml add a description for webservice plugin

    <file type="plugin" id="weblinks" group="webservices">plg_webservices_weblinks.zip</file>