GET /ping

Request GET na /ping/<monitor> to najprostszy sposób na zapisanie zdarzenia monitoringowego. Pasuje do jednolinijkowych skryptów shell, zadań cron, urządzeń IoT, healthchecków z routerów/NAS i wszystkich środowisk, w których ustawienie nagłówka HTTP lub zbudowanie body JSON jest niewygodne.

Request

GET /ping/<monitor>?status=<state>[&...]

<monitor> pochodzi ze ścieżki URL. Wszystkie pola zdarzenia to query parameters.

Autentykacja

Możesz uwierzytelnić się na dwa sposoby. Kompromisy bezpieczeństwa opisuje Autentykacja.

# Nagłówek (zalecane dla ruchu cyklicznego)
curl -H "Authorization: Bearer <api_key>" \
  "https://api.example.com/ping/db-backup?status=complete"

# Query parameter w URL (wygoda — token widoczny w logach/historii/Referer)
curl "https://api.example.com/ping/db-backup?api_key=<api_key>&status=complete"

Nagłówek Authorization ma priorytet. Jeśli jest obecny, ale niepoprawny lub błędnie sformatowany, request zostaje odrzucony nawet gdy podano ?api_key= — brak cichego fallbacku.

Query parameters

Param	Typ	Wymagane	Opis
api_key	string	warunkowo	Klucz API, gdy nie używasz nagłówka Authorization
status	string	tak	Status zdarzenia: run, complete, fail, skip
duration	float	nie	Czas wykonania w sekundach
exit_code	int	nie	Exit code procesu
host	string	nie	Hostname maszyny, na której leciał job
msg	string	nie	Dowolna wiadomość / wycinek logu (URL-encoded)
series	string	nie	Correlation ID grupujący run/complete/fail tego samego uruchomienia

Przykłady

Lifecycle zadania (skorelowany przez series)

SERIES=$(uuidgen)
curl "https://api.example.com/ping/db-backup?status=run&series=$SERIES"
# ... job leci ...
curl "https://api.example.com/ping/db-backup?status=complete&series=$SERIES&duration=47.3&exit_code=0"

Błąd z wiadomością

curl "https://api.example.com/ping/db-backup?status=fail&msg=DB+timeout&exit_code=1"

Skip (maintenance window)

curl "https://api.example.com/ping/payment-service?status=skip"

Wpis crontab (auth nagłówkiem)

0 3 * * *  /usr/local/bin/pg_dump db > /backups/db.sql && \
  curl -s -H "Authorization: Bearer $API_KEY" \
    "https://api.example.com/ping/db-backup?status=complete" >/dev/null

Response

200 OK

{ "status": "success", "message": "Ping accepted", "monitor": "db-backup", "timestamp": 1779650795 }

400 Bad Request

{ "error": "required field missing: status" }

401 Unauthorized

{ "error": "unauthorized" }

Dla bogatszych payloadów (tagi, projekty, strukturalne pola), użyj POST /ping z body JSON.