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](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:

```json
{
  "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:

```json
{
  "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):

```json
{
    "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):

```json
{
    "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):

```json
{
    "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):

```json
{
    "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
            }
        }
    ]
}
```