Szybkie wprowadzenie do API

Ten dokument opisuje podstawy korzystania z API i jest przeznaczony dla nowych użytkowników.

Jeśli szukasz informacji na temat działania konkretnej operacji API, zajrzyj do interaktywnej dokumentacji.

Jeśli dotychczas korzystałeś z poprzedniej wersji API, zajrzyj do instrukcji migracji.

Wymagania wstępne

Potrzebne będą:

klient HTTP - większość przykładów będzie korzystała z konsolowego narzędzia curl,
konto w Monit24.pl - możesz założyć je tutaj.

We wszystkich przykładach, w których występuje "USERNAME" i "PASSWORD", zastąp je swoim loginem i hasłem.

Proste zapytanie do API

Aby pobrać listę dostępnych stacji monitorujących, wykonaj w konsoli:

curl 'https://api.monit24.pl/v3/sensors'

To zapytanie zwróci zakodowaną w JSON tablicę dziesięciu obiektów reprezentujących stacje monitorujące, domyślnie posortowanych rosnąco po identyfikatorze stacji. Operacje zwracające listę obiektów (a taką jest pobranie listy stacji) domyślnie zwracają jedynie pierwsze 10 obiektów, zaś nagłówek HTTP "X-Total-Count" zawiera liczbę wszystkich obiektów. Można tę informację wykorzystać np. w implementacji listy stacji monitorujących z podziałem na strony.

Limit liczby zwracanych obiektów można zmienić za pomocą parametru limit (maksymalny dozwolony to 1000), zaś kolejne strony można pobrać za pomocą parametru offset (liczba początkowych obiektów, które należy pominąć). Na przykład jeśli zachodzi potrzeba wyświetlenia 15 elementów na stronie i wyświetenia trzeciej strony, można użyć zapytania:

curl 'https://api.monit24.pl/v3/sensors?limit=15&offset=30'

Więcej informacji o pobieraniu obiektów

Autentykacja

Lista stacji monitorujących jest publiczna, więc nie wymaga podania loginu i hasła, aby ją pobrać. Jednak większość operacji API takiej autentykacji wymaga. Najprostszym sposobem autentykacji jest HTTP Basic Auth. W programie curl można w tym celu użyć parametru "-u", z loginem i hasłem oddzielonym dwukropkiem:

curl -u USERNAME:PASSWORD 'https://api.monit24.pl/v3/groups'

Powyższe zapytanie zwróci listę grup usług, do których mamy dostęp (ponownie - domyślnie pierwszych 10). Bez podania danych logowania zapytanie zakończyłoby się błędem HTTP 401 Unauthorized.

Więcej informacji o autentykacji

Tworzenie nowych obiektów

Aby utworzyć nową grupę usług, należy wykonać zapytanie POST. Na przykład:

curl -u USERNAME:PASSWORD -X POST -H 'Content-Type: application/json' \
   -d '{"name":"Nowa grupa"}' 'https://api.monit24.pl/v3/groups'

Poszczególne parametry powyższego zapytania mają następujące znaczenie:

-X POST - zmiana metody HTTP na POST (domyślną metodą w curl jest GET).
-H 'Content-Type: application/json' - ustawienie nagłówka Content-Type (typ zawartości) na JSON - API wymaga tego dla operacji w których przesyłana jest zawartość w wywołaniu HTTP.
-d '{"name":"Nowa grupa"}' - zakodowana w JSON treść zapytania. W przypadku tworzenia nowej grupy jest wymagane jedynie podanie jej nazwy, inne ustawienia przyjmą domyślne wartości.

W odpowiedzi zostanie zwrócony identyfikator nowej grupy, na przykład:

{
   "id" : 1000
}

Tak utworzoną grupę można pobrać zapytaniem GET:

curl -u USERNAME:PASSWORD 'https://api.monit24.pl/v3/groups/1000'

Więcej informacji o tworzeniu obiektów

Modyfikacja obiektów

Obiekty można modyfikować wysyłając na ich adres nową reprezentację za pomocą metody PUT. Na przykład jeśli w wyniku powyższego zapytania została pobrana następująca grupa:

{
   "assigned_sensor_ids" : {
       "default" : [1, 2],
       "ipv6" : [3],
       "mobile" : [6],
       "webappcheck" : [4, 5],
   },
   "id" : 1000,
   "is_default" : true,
   "periodic_daily_reports" : true,
   "periodic_monthly_reports" : true,
   "periodic_weekly_reports" : true,
   "name" : "Nowa grupa",
   "owner_id" : 100,
   "sensor_ids" : [
      1,
      2
   ]
}

to można zmienić jej nazwę i wyłączyć wysyłanie raportów dobowych za pomocą zapytania:

curl -u USERNAME:PASSWORD -X PUT -H 'Content-Type: application/json' \
   -d '{
   "assigned_sensor_ids" : {
       "default" : [1, 2],
       "ipv6" : [3],
       "mobile" : [6],
       "webappcheck" : [4, 5],
   },
   "id" : 1000,
   "is_default" : true,
   "periodic_daily_reports" : false,
   "periodic_monthly_reports" : true,
   "periodic_weekly_reports" : true,
   "name" : "Nowa grupa ze zmienioną nazwą",
   "owner_id" : 100,
   "sensor_ids" : [
      1,
      2
   ]
}' 'https://api.monit24.pl/v3/groups/1000'

Nie jest konieczne wysyłanie całego obiektu grupy jeśli zmieniamy tylko niektóre z jego pól. W tym przypadku zapytanie miałoby taki sam efekt, gdyby zostało wysłane jedynie:

curl -u USERNAME:PASSWORD -X PUT -H 'Content-Type: application/json' \
   -d '{
   "periodic_daily_reports" : false,
   "name" : "Nowa grupa ze zmienioną nazwą"
}' 'https://api.monit24.pl/v3/groups/1000'

Więcej informacji o modyfikowaniu obiektów

Usuwanie obiektów

Do usuwania obiektów służy metoda HTTP DELETE. Na przykład aby usunąć grupę, możemy wykonać:

curl -u USERNAME:PASSWORD -X DELETE 'https://api.monit24.pl/v3/groups/1000'

Więcej informacji o usuwaniu obiektów

Pozostałe zasoby

W podobny sposób można obsługiwać pozostałe zasoby Monit24.pl, na przykład:

usługi - services,
kody błędów monitoringu - error_types,
adresy powiadomień - notification_addresses,
pakiety - packages,
raporty okresowe - periodic_report_addresses,
zawieszenia monitoringu - suspensions,
typy usług - service_types,

Więcej informacji o najważniejszych zasobach

Autoryzacja

Nie na wszystkich obiektach można wykonywać wszystkie operacje. O tym, jakie operacje możemy wykonać, decyduje stowarzyszony z obiektem obiekt "permissions", zależny od użytkownika wywołującego operację. Na przykład dla grupy może on wyglądać następująco:

curl -u USERNAME:PASSWORD 'https://api.monit24.pl/v3/groups/1000/permissions'

{
   "create_periodic_report_addresses" : true,
   "create_notification_addresses" : true,
   "create_services" : true,
   "delete" : false,
   "own" : true,
   "read" : true,
   "send_test_sms_notifications" : true,
   "share" : true,
   "update" : true
}

Poszczególne pola określają, co możemy zrobić z wybraną grupą. Ich znaczenie jest szerzej opisane na liście konwencji stosowanych w API.

Więcej informacji o uprawnieniach

Dalsze kroki

W dalszej kolejności proponujemy zapoznać się z listą przykładów wywołań operacji API, listą wykorzystywanych konwencji, opisem najważniejszych obiektów występujących w systemie lub przejść od razu do szczegółowej interaktywnej dokumentacji.