fogping's web UI and the Zabbix template talk to fogping through this API. The same rules hold in pingping and vrf-ping, so a client written for one reads the others the same way.
The same API in machine-readable form: openapi.yaml (OpenAPI 3.1).
A test (TestOpenAPIMatchesRoutes) fails when it and the registered routes differ.
These are enforced by tests (api_test.go): code that breaks one does not pass CI.
-
Version. This is API version 1. Every
/api/response carries the headerAPI-Version: 1. Within version 1, changes are only additive: new endpoints, new optional request fields, new response fields. Removing or renaming a field, or changing what it means, needs a new prefix/api/v2/, and/api/keeps answering as before. -
Methods. Every endpoint names its methods. Reads are
GET, createsPOST, replacementsPUT, deletionsDELETE, actionsPOST. Any other method gets405with anAllowheader. -
JSON in, JSON out. A request with a body sends
Content-Type: application/json(anything else gets415). Every response, errors included, isapplication/json; charset=utf-8, except the targets export, which is a JSON file sent as a download. -
One error shape. Every error is
{"error": "<message for a person>", "code": "<code for a program>"}. Programs branch oncode(or the status); people readerror. The codes:Status code400 bad_request401 unauthorized403 forbidden404 not_found405 method_not_allowed409 conflict413 too_large415 unsupported_media_type429 rate_limited(withRetry-After)500 internal503 unavailableAn unknown path under
/api/is a404in the same shape. -
Names. JSON keys are
snake_case, in requests and responses. Times are Unix seconds; a duration or size says its unit in its name (interval_sec,window_sec,retention_days); a percentage ends in_pct. The one exception is the compact sample format of/api/series(below), which predates these rules and is kept for compatibility. -
Authentication. The web UI signs in with
POST /api/loginand then sends thefogping_sessioncookie. Machine clients use a bearer token (Authorization: Bearer …) where an endpoint says so. The/api/statstoken is read-only by design: it can read statistics and nothing else, and there are no write tokens. Every write needs a signed-in session. A missing or bad credential is401. Writes also refuse a cross-origin browser request (403). -
Documented. Every endpoint is listed below. A test compares this table with the routes the code registers, both ways.
| Method | Path | Auth | What it does |
|---|---|---|---|
| POST | /api/login | none | Sign in. Body {"user": "…", "pass": "…"}; sets the session cookie. Repeated failures from one address get 429. |
| POST | /api/logout | none | Sign out: the session ends on the server too. Safe to call without one. |
| GET | /api/version | none / session | {"version"} for everyone; with a session (or no login configured) also retention_days, hot_days, editable. |
| GET | /api/probe-types | session | The probe types this fogping can run, in display order: [{"type", "label", "uses_port", "options"}]; options are the type's own settings (spec). The UI builds its type filter and form from it. |
| GET | /api/targets | session | Every target with its last-hour and last-day summary. |
| POST | /api/targets | session, --edit |
Create a target. Unknown fields are refused. Body fields: name, type, host, port, pace, interval_sec, and options (an object; keys per the type's spec). |
| PUT | /api/targets/{id} | session, --edit |
Replace a target. |
| DELETE | /api/targets/{id} | session, --edit |
Delete a target (its history is kept). |
| GET | /api/targets/export | session | The target list as a netping-targets file (format). |
| POST | /api/targets/import | session, --edit |
Import a netping-targets file. ?dry_run=1 reports without applying. |
| GET | /api/series | session | Rounds for one target: ?target=NAME and either ?minutes=N or ?from=&to= (Unix seconds). |
| GET | /api/stats | bearer token | Per-target summary of the last 5 minutes, for Zabbix. Exists only with --zabbix (template). |
"session" means: a signed-in session when fogping was started with a login, anyone otherwise.
{"tier": "raw", "rounds": [{"t": 1700000000, "s": 20, "r": 19, "ms": [12.1, 12.4], "b": true, "z": 3.8}]}
{"tier": "hourly", "buckets": [{"t": 1700000000, "q": [10.2, 12.0, 14.1, 19.5, 30.0], "loss": 1.5, "n": 60, "bursts": 1}]}Up to a day the answer is raw: one entry per round — t time (Unix seconds),
s packets sent, r received, ms every reply's round-trip time in
milliseconds, b true when the round was flagged as a loss burst, z the robust
z-score behind that flag. Longer windows are hourly: one bucket per hour —
q min/p50/p90/p99/max in ms (absent when every packet was lost), loss
percent of packets lost, n rounds in the bucket, bursts flagged rounds.
A round that could not be measured at all (DNS failed, no ICMP socket) has s: 0
and e set to the reason. It is not loss: it is left out of every statistic, and
/api/targets and /api/stats count such rounds apart as probe_errors.