API Nodea v1 — wprowadzenie: base URL, tokeny, scope'y, limity | Nodea

API Nodea (wersja v1) daje programowy dostęp do tego samego, co panel /app: monitoringu stron i heartbeatów, integracji i eskalacji alertów, serwerów, kluczy SSH, stref DNS, urządzeń Vault oraz konta (profil, zgłoszenia, rozliczenia, domeny, hosting, migracje). Interfejs jest w pełni REST-owy, przyjmuje i zwraca JSON, a każdy zasób jest ograniczony do właściciela tokenu.

Ten wpis to wprowadzenie — opisuje bazowy adres, uwierzytelnianie, zakresy uprawnień (scope'y), limity zapytań, format błędów i paginację. Dokumentacja poszczególnych modułów (endpointy, pola, przykłady) znajduje się w osobnych wpisach tej kolekcji.

Base URL

Wszystkie ścieżki API v1 są względem jednego prefiksu:

https://app.nodea.io/api/v1

Na przykład endpoint tożsamości tokenu to GET /api/v1/me, a lista monitorowanych stron — GET /api/v1/websites. Wszystkie odpowiedzi mają Content-Type: application/json. Wysyłając dane, ustaw nagłówki Accept: application/json oraz Content-Type: application/json.

Uwierzytelnianie

API v1 chroni guard Passport (auth:api). Autoryzujesz się Personal Access Tokenem (PAT) — długoterminowym tokenem OAuth, który wygenerujesz sam w panelu.

Jak wygenerować token

1. Zaloguj się do panelu i wejdź w ustawienia konta → Tokeny API (/app/account/api-tokens).
2. Kliknij Utwórz token, nadaj mu nazwę i zaznacz tylko te scope'y, których dana integracja naprawdę potrzebuje.
3. Skopiuj pełną wartość tokenu od razu — jest pokazywana tylko raz. Później w panelu widoczna jest wyłącznie nazwa i lista scope'ów.

Nagłówek autoryzacji

Token dołączasz do każdego żądania w nagłówku Authorization jako Bearer:

Authorization: Bearer 1|AbCdEf0123456789...

Żądanie bez ważnego tokenu — lub z tokenem odwołanym — otrzyma 401 Unauthorized. Token możesz w każdej chwili unieważnić w panelu; unieważnienie działa natychmiast.

Scope'y (zakresy uprawnień)

Token nie daje pełnego dostępu do konta — niesie tylko te uprawnienia, które zaznaczysz przy jego tworzeniu. Scope'y są zorganizowane w 4 grupy modułowe, każda w trzech poziomach: read (listowanie i odczyt), write (tworzenie, aktualizacja i akcje nieniszczące — np. „uruchom teraz", pauza, test powiadomienia) oraz delete (akcje nieodwracalne — usunięcie zasobu, zatrzymanie VM, terminacja hostingu).

Łącznie daje to 12 scope'ów (4 grupy × 3 poziomy):

Grupa	Scope'y	Co autoryzuje
monitoring	monitoring:read monitoring:write monitoring:delete	Strony (websites), heartbeaty, raporty i strony statusu (status pages). read = listy i szczegóły; write = tworzenie/edycja, „uruchom teraz", pauza/wznowienie, okna serwisowe; delete = usunięcie monitora wraz z historią.
alerting	alerting:read alerting:write alerting:delete	Integracje powiadomień, grupy powiadomień, polityki eskalacji i udostępnienia (sharing). write obejmuje test powiadomienia; delete = usunięcie integracji/polityki/udostępnienia.
infra	infra:read infra:write infra:delete	Serwery, klucze SSH, strefy DNS i urządzenia Vault. write = tworzenie/edycja i akcje operacyjne; delete = akcje niszczące, np. zatrzymanie VM czy usunięcie klucza/strefy.
account	account:read account:write account:delete	Profil, zgłoszenia (tickety), rozliczenia (billing), domeny, hosting i migrator. delete = akcje nieodwracalne, np. terminacja hostingu.

Zasada jest prosta: nadawaj tokenowi minimum uprawnień. Integracja tylko odczytująca status monitoringu potrzebuje wyłącznie monitoring:read — nie dawaj jej :write ani :delete. Endpoint dziedziczy też te same flagi funkcji (Pennant) co panel, więc jeśli moduł jest wyłączony dla Twojego konta, token go nie odblokuje.

Żądanie tokenem bez wymaganego scope'a otrzyma 403 Forbidden.

Rate limit (limit zapytań)

API v1 jest ograniczone do 240 żądań na minutę na token. Licznik jest kluczowany po tokenie (żądania bez tokenu spadają na limit per-IP). Po przekroczeniu limitu otrzymasz 429 Too Many Requests; nagłówki X-RateLimit-Limit, X-RateLimit-Remaining oraz Retry-After podpowiadają, kiedy ponowić żądanie. Buforuj odpowiedzi i nie odpytuj w pętli częściej, niż to konieczne.

Format błędów

Błędy zwracane są jako JSON o kształcie:

{
  "message": "Opis błędu, gotowy do pokazania człowiekowi.",
  "code": "opcjonalny_kod_maszynowy"
}

Przy błędach walidacji (422) odpowiedź zawiera dodatkowo obiekt errors z listą komunikatów per pole. Kody statusu HTTP, których używa API:

Kod	Znaczenie
400	Bad Request — żądanie źle sformułowane.
401	Unauthorized — brak tokenu, token nieważny lub odwołany.
403	Forbidden — token nie ma wymaganego scope'a albo moduł jest wyłączony.
404	Not Found — zasób nie istnieje lub nie należy do właściciela tokenu.
409	Conflict — akcja koliduje ze stanem zasobu (np. duplikat).
422	Unprocessable Entity — błąd walidacji (szczegóły w errors).
429	Too Many Requests — przekroczony rate limit.
502	Bad Gateway — błąd usługi zależnej (np. dostawcy infrastruktury).
503	Service Unavailable — chwilowa niedostępność (np. tryb serwisowy).

Paginacja

Endpointy zwracające listy są paginowane. Rozmiar strony sterujesz parametrem per_page (domyślnie 20, maksymalnie 100), a numer strony — parametrem page. Odpowiedź niesie tablicę data oraz metadane paginacji (bieżąca strona, liczba stron, łączna liczba rekordów).

Endpointy przeglądające bardzo długie historie (np. pojedyncze przebiegi monitoringu) używają simplePaginate — zwracają tylko wskaźniki „następna/poprzednia strona" bez zliczania wszystkich rekordów, co jest znacznie tańsze przy milionach wierszy. Iteruj po nich, podążając za linkiem do następnej strony, a nie licząc z góry liczby stron.

Przykład: curl

Najprostszy test tokenu to endpoint GET /api/v1/me, który zwraca tożsamość właściciela tokenu i przyznane scope'y.

Bez tokenu — 401:

curl -i https://app.nodea.io/api/v1/me

HTTP/2 401
Content-Type: application/json

{ "message": "Unauthenticated." }

Z ważnym tokenem — 200:

curl -s https://app.nodea.io/api/v1/me \
  -H "Authorization: Bearer 1|AbCdEf0123456789..." \
  -H "Accept: application/json"

{
  "data": {
    "id": 42,
    "name": "Jan Kowalski",
    "email": "jan@example.com",
    "scopes": ["monitoring:read", "alerting:read"]
  }
}

Gdy to działa, przejdź do dokumentacji konkretnego modułu — każdy opisuje swoje endpointy, parametry i przykłady żądań.