MokoSuiteClient/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"]
}
```

## 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.