MokoWaaS/wiki/api-endpoints.md

API Endpoints

MokoWaaS provides 6 remote management endpoints accessible via query string parameter. All endpoints require HTTPS and Bearer token authentication.

Authentication

All endpoints require the health_api_token as a Bearer token in the Authorization header:

Authorization: Bearer <health_api_token>

The token is auto-generated during plugin installation and stored as a read-only parameter in the plugin configuration. It can also be passed as a token query parameter as a fallback.

Token validation uses hash_equals() for timing-safe comparison. If no token is configured, the endpoint returns HTTP 503. An invalid token returns HTTP 401.

Endpoints

1. Health Check

GET /?mokowaas=health

Runs 16 diagnostic checks and returns a comprehensive health report. See Health Monitoring for full documentation of all checks and response format.

Response: JSON object with status (ok/degraded/error), reason, timestamp, checks, and meta.

HTTP Status: 200 (ok/degraded), 503 (error).

---

2. Site Info

GET /?mokowaas=info

Returns a compact summary of the Joomla site.

Response:

Field	Description
site_name	Joomla site name
site_url	Site root URL
joomla_version	Joomla CMS version
php_version	PHP version
db_type	Database driver (e.g. pdomysql)
debug	Whether debug mode is on
sef	Whether SEF URLs are enabled
caching	Whether caching is enabled
articles	Total article count
users	Total user count
extensions	Number of enabled extensions
brand	Configured brand name
plugin_version	MokoWaaS plugin version

---

3. Remote Install

POST /?mokowaas=install
Content-Type: application/json

{"url": "https://example.com/extension.zip"}

Downloads and installs a Joomla extension from the provided URL. The extension is downloaded to a temporary directory, extracted, and installed using Joomla's installer API.

Response: JSON object with status, extension name, and message.

HTTP Status: 200 (success), 400 (missing URL), 405 (not POST), 500 (install failed).

---

4. Update Check

POST /?mokowaas=update

Clears the Joomla update cache and triggers a fresh update check via Updater::findUpdates().

Response:

Field	Description
status	ok
updates_found	Number of available updates
message	Human-readable summary

HTTP Status: 200 (success), 405 (not POST), 500 (failed).

---

5. Cache Clear

POST /?mokowaas=cache

Clears the Joomla site cache, admin cache, and PHP OPcache (if available).

Response:

Field	Description
status	ok
message	Cache cleared

HTTP Status: 200 (success), 405 (not POST), 500 (failed).

---

6. Backup (Akeeba)

POST /?mokowaas=backup
Content-Type: application/json

{"profile": 1}

Triggers an Akeeba Backup using the specified profile (defaults to profile 1). Requires Akeeba Backup to be installed.

Response:

Field	Description
status	started
profile	Backup profile ID used
message	Backup started

HTTP Status: 200 (started), 404 (Akeeba not installed), 405 (not POST), 500 (failed), 501 (Akeeba Engine not loadable).

Error Responses

All endpoints return errors in a consistent format:

{
  "error": "Error description",
  "message": "Additional detail (optional)"
}

Common Error Codes

HTTP Status	Meaning
400	Bad request (unknown action, missing parameters)
401	Invalid or missing authentication token
405	Wrong HTTP method (e.g. GET when POST is required)
500	Server error during operation
503	No API token configured

Unknown Actions

Requesting an unknown action returns HTTP 400 with the list of available actions:

{
  "error": "Unknown action",
  "action": "invalid",
  "available": ["health", "install", "update", "cache", "backup", "info", "reset", "snapshot"]
}

Joomla REST API Routes

In addition to the query-string endpoints above, MokoWaaS registers standard Joomla API routes via the plg_webservices_mokowaas plugin:

Route	Controller	Description
GET /api/v1/mokowaas/health	HealthController	Full site health diagnostics
POST /api/v1/mokowaas/cache	CacheController	Clear all caches
POST /api/v1/mokowaas/update	UpdateController	Trigger update check
POST /api/v1/mokowaas/install	InstallController	Install extension from ZIP URL
POST /api/v1/mokowaas/reset	ResetController	Restore site to baseline snapshot
GET/POST /api/v1/mokowaas/snapshot	SnapshotController	List or create snapshots
POST /api/v1/mokowaas/sync	SyncController	Push content to all sync targets
POST /api/v1/mokowaas/sync-receive	SyncReceiveController	Receive content from source site
GET /api/v1/mokowaas/extensions	ExtensionsController	List installed extensions

These routes use Joomla's standard API authentication (API token in X-Joomla-Token header) and are useful for integrations that already use the Joomla API framework.

Install Endpoint (REST API)

POST /api/index.php/v1/mokowaas/install
X-Joomla-Token: <api-token>
Content-Type: application/json

{"url": "https://git.mokoconsulting.tech/.../plg_system_mokowaas-02.20.00.zip"}

Downloads the ZIP from the given URL and installs it via Joomla's Installer. Requires a Joomla API token with core.manage permission on com_installer.

Constraints:

• URL must use http or https scheme
• URL path must end in .zip
• Maximum download size: 64 MB

Success Response (HTTP 200):

{
    "status": "ok",
    "message": "Extension installed successfully",
    "extension": {
        "name": "MokoWaaS",
        "version": "02.20.00",
        "type": "plugin"
    },
    "source_url": "https://git.mokoconsulting.tech/.../plg_system_mokowaas-02.20.00.zip"
}

Error Responses:

HTTP Status	Condition
400	Missing url field, non-HTTPS URL, or URL not ending in .zip
403	API token lacks core.manage on com_installer
405	Request method is not POST
500	Download or installation failed

Reset Endpoint (REST API)

POST /api/index.php/v1/mokowaas/reset
X-Joomla-Token: <api-token>
Content-Type: application/json

{"baseline": "default"}

Restores the site to a named baseline snapshot. The baseline field is optional and defaults to the active baseline configured in the plugin.

Requires core.manage permission on com_plugins.

Success Response (HTTP 200):

{
    "status": "ok",
    "message": "Site restored to baseline: default",
    "baseline": "default",
    "restored_tables": 15,
    "media_restored": true
}

Snapshot Endpoint (REST API)

List snapshots:

GET /api/index.php/v1/mokowaas/snapshot
X-Joomla-Token: <api-token>

Create snapshot:

POST /api/index.php/v1/mokowaas/snapshot
X-Joomla-Token: <api-token>
Content-Type: application/json

{"name": "my-baseline"}

The name field is optional and defaults to the active baseline name.

Success Response (HTTP 200):

{
    "status": "ok",
    "message": "Snapshot created",
    "name": "my-baseline",
    "tables": 15,
    "has_media": true
}

Extensions Endpoint (REST API)

GET /api/index.php/v1/mokowaas/extensions
X-Joomla-Token: <api-token>

Lists all installed Joomla extensions with version, enabled/protected/locked status, and update server info.

Query filters:

Parameter	Description	Example
type	Filter by extension type	?type=plugin
search	Search name or element	?search=moko
enabled	Filter by enabled status	?enabled=1

Query-string equivalent: GET /?mokowaas=extensions&search=moko&type=plugin

Requires core.manage on com_installer.

Success Response (HTTP 200):

{
    "status": "ok",
    "count": 3,
    "extensions": [
        {
            "extension_id": 456,
            "name": "System - MokoWaaS",
            "type": "plugin",
            "element": "mokowaas",
            "folder": "system",
            "client_id": 0,
            "enabled": true,
            "protected": true,
            "locked": false,
            "version": "02.21.00",
            "author": "Moko Consulting",
            "update_server": {
                "name": "MokoWaaS Update Server",
                "location": "https://git.mokoconsulting.tech/.../updates.xml",
                "enabled": true
            }
        }
    ]
}