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"]
}

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
GET /api/v1/mokowaas/health	HealthController
POST /api/v1/mokowaas/cache	CacheController
POST /api/v1/mokowaas/update	UpdateController

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.