mirror of
https://github.com/Cacti/cacti.git
synced 2026-10-29 16:17:14 +09:00
Thomas Vincent
79a9ae0351
* build: raise the 1.3 floor to PHP 8.3 RHEL 10 ships 8.3 in AppStream and dropped modularity, so an 8.4 floor would put every RHEL, Alma and Rocky 10 install on Remi. Ubuntu 24.04 is 8.3 as well, which makes it the lowest common denominator of the current LTS fleet. Signed-off-by: Thomas Vincent <thomasvincent@gmail.com> * docs: raise the documented PHP floor to 8.3 The 1.2.x column keeps 8.1, which still matches that branch's composer constraint. Signed-off-by: Thomas Vincent <thomasvincent@gmail.com> * ci: run process lock coverage on PHP 8.3 * fix: finish PHP 8.3 floor cleanup Signed-off-by: Thomas Vincent <thomasvincent@gmail.com> --------- Signed-off-by: Thomas Vincent <thomasvincent@gmail.com>
109 lines
3.0 KiB
Markdown
109 lines
3.0 KiB
Markdown
# Cacti RESTful Slim API
|
|
|
|
This project provides a RESTful API for accessing Cacti monitoring data using the Slim PHP framework.
|
|
|
|
## Overview
|
|
|
|
The API exposes endpoints to retrieve information about hosts, host templates, poller status, graph lists, Cacti status, boost status, database connectivity, and plugin thresholds. All responses are in JSON format.
|
|
|
|
**This API is not production ready.**
|
|
|
|
It refuses to answer unless it is deliberately switched on, because no route in
|
|
it authenticates or authorises anything. Every endpoint would answer whoever
|
|
reached the URL. To run it for development, enable it in the database:
|
|
|
|
```sql
|
|
REPLACE INTO settings (name, value) VALUES ('api_enabled', 'on');
|
|
```
|
|
|
|
Error details are withheld on the same basis, since they carry stack traces and
|
|
file paths. To see them while developing:
|
|
|
|
```sql
|
|
REPLACE INTO settings (name, value) VALUES ('api_developer_mode', 'on');
|
|
```
|
|
|
|
Neither setting appears in the web interface on purpose. Adding a toggle that
|
|
exposes host inventory without a password would be worse than leaving the
|
|
switch where an operator has to mean it. See ADR 0001 for the authentication
|
|
this is waiting on.
|
|
|
|
|
|
To run the API for development:
|
|
|
|
```bash
|
|
php -S 127.0.0.1:8080 -t public public/index.php
|
|
```
|
|
|
|
For production, this should be served by a proper web server (Apache, Nginx, etc.).
|
|
|
|
## API Versioning
|
|
|
|
The API uses URL path versioning. All endpoints are prefixed with a version number:
|
|
- `/v1/` - Current stable version
|
|
|
|
## Endpoints
|
|
|
|
- `GET /`
|
|
Returns a welcome message.
|
|
|
|
### Version 1 (v1) Endpoints
|
|
|
|
#### Info Endpoints
|
|
- `GET /v1/info/hosts`
|
|
Returns a list of hosts.
|
|
**Allowed query parameters:**
|
|
- `host_id`
|
|
- `poller_id`
|
|
- `site_id`
|
|
- `template_id`
|
|
- `status`
|
|
|
|
- `GET /v1/info/host_templates`
|
|
Returns host template information. Accepts `template_id` as a query parameter.
|
|
|
|
- `GET /v1/info/graph_list`
|
|
Returns a list of graphs. Accepts `host_id` as a query parameter.
|
|
|
|
#### Status Endpoints
|
|
- `GET /v1/status/poller_status`
|
|
Returns poller status. Accepts `poller_id` as a query parameter.
|
|
|
|
- `GET /v1/status/cacti_status`
|
|
Returns the status of the Cacti system.
|
|
|
|
- `GET /v1/status/boost_status`
|
|
Returns the status of the Cacti Boost system.
|
|
|
|
- `GET /v1/status/api_db_ping`
|
|
Checks database connectivity.
|
|
|
|
- `GET /v1/status/cacti_db_status`
|
|
Returns metrics for the main Cacti database.
|
|
|
|
#### Plugin Endpoints
|
|
- `GET /v1/plugin/thold/thresholds`
|
|
Returns threshold information from the thold plugin.
|
|
|
|
- `GET /v1/plugin/thold/status`
|
|
Returns threshold status information.
|
|
|
|
## Usage
|
|
|
|
1. Install dependencies with Composer.
|
|
2. Configure your web server to serve the `public/` directory.
|
|
3. Access the API endpoints as described above using the versioned URLs (e.g., `/v1/info/hosts`).
|
|
|
|
## Requirements
|
|
|
|
- PHP 8.3 or higher (within the supported PHP 8.x series)
|
|
- Composer
|
|
- Cacti database and configuration
|
|
|
|
## TODO
|
|
- Import Cacti base db_functions
|
|
- Logging
|
|
- Authentication/Authorization
|
|
- Rate limiting
|
|
- API documentation (OpenAPI/Swagger)
|