Open-source software for Joomla, Gitea, and web platforms. Home of MokoSuite, MokoGitea, and MokoCLI.

Tennessee

architecture/joomla-rest-api.-

Joomla REST API Architecture

Web Services plugin pattern for MokoSuite REST APIs.

Overview

Each MokoSuite component exposes a REST API through a companion plg_webservices_{name} plugin. The API follows JSON:API format and uses Joomla's built-in Web Services infrastructure.

Endpoint Convention

GET    /api/v1/{component}/{resources}          # List records
GET    /api/v1/{component}/{resources}/{id}      # Get single record
POST   /api/v1/{component}/{resources}           # Create record
PATCH  /api/v1/{component}/{resources}/{id}      # Update record
DELETE /api/v1/{component}/{resources}/{id}      # Delete record

Examples:

GET    /api/v1/mokosuitebackup/backups
GET    /api/v1/mokosuitebackup/profiles/3
POST   /api/v1/mokosuitebackup/backup           # Start a backup
GET    /api/v1/mokosuitecross/posts
GET    /api/v1/mokoog/tags

Route Registration

The webservices plugin registers routes in onBeforeApiRoute:

namespace MokoConsulting\Plugin\WebServices\MokoSuiteBackup\Extension;

use Joomla\CMS\Plugin\CMSPlugin;
use Joomla\Event\SubscriberInterface;
use Joomla\Router\Route;

final class MokoSuiteBackupWebServices extends CMSPlugin implements SubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return ['onBeforeApiRoute' => 'registerRoutes'];
    }

    public function registerRoutes(Event $event): void
    {
        $router = $event->getArgument('router');

        $router->createCRUDRoutes(
            'v1/mokosuitebackup/backups',
            'backups',
            ['component' => 'com_mokosuitebackup']
        );

        $router->createCRUDRoutes(
            'v1/mokosuitebackup/profiles',
            'profiles',
            ['component' => 'com_mokosuitebackup']
        );

        // Custom action route
        $router->addRoute(
            new Route(
                ['POST'],
                'v1/mokosuitebackup/backup',
                'backup.run',
                [],
                ['component' => 'com_mokosuitebackup']
            )
        );
    }
}

Authentication

All API requests require a Bearer token:

Authorization: Bearer {joomla_api_token}

Tokens are created in Joomla admin under Users > Manage > API Tokens.

Response Format

Responses follow JSON:API specification:

{
  "links": {
    "self": "https://example.com/api/v1/mokosuitebackup/backups"
  },
  "data": [
    {
      "type": "backups",
      "id": "42",
      "attributes": {
        "profile_id": 1,
        "status": "complete",
        "archive_size": 52428800,
        "created_at": "2026-06-01T12:00:00Z"
      }
    }
  ],
  "meta": {
    "total-pages": 3
  }
}

Pagination

Use query parameters:

GET /api/v1/mokosuitebackup/backups?page[offset]=20&page[limit]=10

Default limit: 20. Maximum limit: 50.

Filtering

GET /api/v1/mokosuitebackup/backups?filter[status]=complete&filter[profile_id]=1

Error Responses

{
  "errors": [
    {
      "title": "Record not found",
      "code": 404
    }
  ]
}

Standard HTTP status codes: 200 (OK), 201 (Created), 204 (No Content), 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 422 (Validation Error).

Pages