Spis treści

Pobranie pojedynczego obiektu

fields
embed

Pobranie listy obiektów

fields
embed
sort
limit
offset
query
Filtry
Filtry dopasowujące

Tworzenie obiektów
Modyfikacja obiektów
Usuwanie obiektów

Standardowe operacje

Interfejs znacznej części operacji API wpisuje się w jeden ze standardowych schematów, odpowiadającym operacjom CRUD (Create, Read, Update i Delete) na obiektach. Poniżej są opisane właściwości takich standardowych operacji.

Pobranie pojedynczego obiektu

Pojedynczy obiekt (usługę, grupę itp.) można pobrać wykonując zapytanie GET na adres tego obiektu. W przypadku często wykorzystywanych zasobów będzie miał on zazwyczaj postać https://api.monit24.pl/v3/ZASOB/ID, gdzie ZASOB to nazwa zasobu (np. services, groups itp.), zaś ID to identyfikator obiektu (najczęściej dodatnia liczba całkowita).

Operacja pobierania pojedynczego obiektu udostępnia dwa parametry GET - fields oraz embed.

fields

Parametr fields służy do zawężenia pól obiektu, które należy zwrócić (domyślnie są zwracane wszystkie pola). Powinien zawierać tablicę nazw pól obiektu. Przykładowo, aby pobrać jedynie nazwę, częstotliwość sprawdzeń i identyfikator grupy dla usługi o identyfikatorze 123456, można użyć wywołania:

curl -u USERNAME:PASSWORD 'https://api.monit24.pl/v3/services/123456?fields=name,interval,group_id'

Zalecane jest pobieranie jedynie pól, które są w danym momencie potrzebne - poza oszczędnością transferu, w niektórych przypadkach API może dodatkowo optymalizować wewnętrzne mechanizmy pobierania tylko niektórych pól.

embed

Parametr embed umożliwia pobranie razem z obiektem innych powiązanych obiektów poprzez ich "dowiązanie" do obiektu jako dodatkowe atrybuty. Jest to tablica symboli obiektów, które chcemy dowiązać, lub ich wybranych pól. Dostępność opcji embed oraz lista dostępnych symboli zależy od konkretnej operacji API.

Przykładowo, aby pobrać usługę razem z grupą, do której należy, można użyć zapytania:

curl -u USERNAME:PASSWORD 'https://api.monit24.pl/v3/services/123456?embed=group'

Spowoduje to dodanie do obiektu usługi pola group zawierającego obiekt grupy, do której należy usługa.

Można także ograniczyć pola dowiązywanego obiektu, podobnie jak w fields - na przykład, aby dowiązać grupę jedynie z jej nazwą i identyfikatorem, można wywołać następujące zapytanie:

curl -u USERNAME:PASSWORD 'https://api.monit24.pl/v3/services/123456?embed=group.id,group.name'

Uwaga: jeśli wywołujący użytkownik nie ma wystarczających uprawnień do pobrania dowiązywanego obiektu, w jego miejsce zostanie wstawiona wartość NULL.

Pobranie listy obiektów

Listę obiektów określonego typu można pobrać za pomocą zapytania GET na adres zasobu odpowiadającego kolekcji tych obiektów. Zazwyczaj będzie on miał postać https://api.monit24.pl/v3/ZASOB, gdzie ZASOB to identyfikator zasobu, np. services, sensors itp.

Operacje pobierania listy obiektów przyjmują następujące parametry GET:

fields

Analogicznie jak dla pobierania pojedynczego obiektu, parametr fields służy do zawężenia listy pobieranych pól dla wszystkich obiektów.

embed

Podobnie, parametr embed działa tak, jak dla pobierania pojedynczego obiektu.

Niezależnie od tego, czy pobieramy listę obiektów, czy pojedynczy obiekt, dostępne są te same dowiązywalne obiekty.

sort

Parametr sort zawiera tablicę nazw pól (lub wybranych pól z dowiązywalnych obiektów), po których należy posortować listę wyników, w kolejności od najbardziej znaczącego. Nazwę pola można poprzedzić znakiem minus ("-"), aby sortować malejąco.

Przykładowo, aby pobrać listę stacji monitorujących posortowaną po nazwie miasta malejąco, a w przypadku takiego samego miasta po identyfikatorze stacji rosnąco, można użyć zapytania:

curl 'https://api.monit24.pl/v3/sensors?sort=-city,id'

Jeśli obiekty mają "oczywisty" identyfikator (np. pole "id"), to domyślnie wyniki sortowane są właśnie po nim, rosnąco.

limit

Nieujemna liczba całkowita określająca, ile maksymalnie obiektów należy zwrócić. Podczas pobierania pierwsze offset obiektów zostanie pominięte, a następnie zostanie zwrócone pierwsze limit z pozostałych, lub wszystkie pozostałe jeśli zostanie ich mniej niż limit. Parametry limit i offset służą do implementacji paginacji wyników. Nagłówek HTTP odpowiedzi X-Total-Count zawiera liczbę wszystkich obiektów (z uwzględnieniem filtrowania) i może zostać użyty do określenia liczby stron przy takiej paginacji.

Uwaga: Maksymalną dopuszczalną wartością parametru limit jest 1000, a domyślną 10.

offset

Określa, ile początkowych obiektów należy pominąć. Razem z limit może służyć do paginacji wyników.

Przykładowo, przy wyświetlaniu 10 stacji monitorujących na stronie listy, trzecią stronę można pobrać za pomocą zapytania:

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

Domyślną wartością parametru offset jest 0.

query

Parametr query służy do prostego wyszukiwania obiektów. Jego głównym zastosowaniem jest implementacja prostych wyszukiwarek, do których można wpisać tekst i otrzymać listę obiektów "pasujących" do niego. Szczegóły algorytmu wyszukiwania i precyzyjna definicja "pasowania" mogą zależeć od typu wyszukiwanych obiektów - korzystając z query użytkownik zdaje się na API w tych kwestiach.

Filtry

Filtrowanie po wartościach pól odbywa się poprzez podanie żądanej wartości w parametrze GET o nazwie takiej jak nazwa pola. Na przykład aby wybrać jedynie stacje monitorujące w Warszawie, można użyć zapytania:

curl 'https://api.monit24.pl/v3/sensors?city=Warszawa'

Wyszukiwanie nie rozróżnia wielkich i małych liter. Filtrowanie jest dostępne jedynie dla wybranych pól obiektów, zależnych od konkretnej operacji API. W niektórych przypadkach możliwe jest także filtrowanie po niektórych polach dowiązywalnych obiektów (nawet jeśli ich nie dowiązujemy). Na przykład, aby wybrać grupy, które możemy usunąć, można użyć filtru po permissions.delete:

curl -u USERNAME:PASSWORD 'https://api.monit24.pl/v3/groups?permissions.delete=true'

Wartości true, false oraz null dopasowują się do odpowiednich wartości binarnych lub JSON-owej wartości NULL.

Podając kilkukrotnie ten sam parametr można zdefiniować więcej niż jedną dopuszczalną wartość. Na przykład, aby wyszukać stacje monitorujące w Warszawie lub Krakowie, można użyć zapytania:

curl 'https://api.monit24.pl/v3/sensors?city=Warszawa&city=Kraków'

Filtry dopasowujące

Od wersji API 3.3 dla niektórych pól typu string możliwe jest używanie filtrów dopasowujących. Filtry takie służą do wyszukiwania określonego tekstu w wartości pola. Użyce filtrów dopasowujących polega na dodaniu tyldy (~) bezpośrednio po nazwie pola. Na przykład zapytanie:

curl -u USERNAME:PASSWORD 'https://api.monit24.pl/v3/services?type.name~=FullPage'

zwróci listę usług typu FullPage, ale także typów zawierających FullPage w nazwie, takich jak FullPageHttps. Podobnie jak standardowe filtry, filtry dopasowujące nie rozróżniają wielkości znaków, określenie ich dla różnych pól oznacza logiczną koniunkcję, a powtórzenie tego samego parametru alternatywę.

Tworzenie obiektów

Jeśli identyfikator obiektu jest znany przed jego utworzeniem, to tworzenie i modyfikacja odbywa się za pomocą tej samej operacji API, wykorzystującej metodę HTTP PUT. Przykładowo, identyfikatorem udostępnienia grupy innemu użytkownikowi jest para (identyfikator grupy, identyfikator konta), znana z góry przed utworzeniem udostępnienia. Dlatego tworzenie nowego udostępnienia działa tak samo, jak jego modyfikacja, na przykład (udostępnienie grupy 1000 użytkownikowi 400):

curl -u USERNAME:PASSWORD -X PUT -H 'Content-Type: application/json' \
   -d '{
   "can_modify_group" : false,
   "can_modify_services" : true
}' https://api.monit24.pl/v3/groups/1000/shares/400

W większości przypadków identyfikator obiektu nie będzie jednak znany przed jego utworzeniem, a zostanie przydzielony przez API po utworzeniu. Wówczas tworzenie obiektu odbywa się za pomocą wywołania POST na adresie URL odpowiedniego zasobu (tego samego, co dla pobierania listy obiektów). Treść takiego zapytania to JSON-owy obiekt zawierający wszystkie dane potrzebne do utworzenia nowego obiektu w API. Format tego obiektu jest definiowany osobno dla każdego zasobu - nie należy zakładać, że jego pola będą np. podzbiorem pól tworzonego obiektu (chociaż w większości przypadków tak właśnie będzie). Jest to zgodne z ogólnymi zasadami działania operacji wykorzystujących metodę POST.

Przykładowo, aby utworzyć nową usługę HTTP monitorującą adres http://monit24.pl co 10 minut, należy wykonać poniższe zapytanie:

curl -u USERNAME:PASSWORD -X POST -H 'Content-Type: application/json' \
   -d '{
   "type_id" : "http",
   "name" : "Test HTTP service",
   "interval" : 600,
   "address" : "monit24.pl"
}' https://api.monit24.pl/v3/services

Jeśli usługa zostanie utworzona poprawnie, API odpowie kodem HTTP 201 Created. Treść odpowiedzi będzie zawierała identyfikator nowej usługi:

{
   "id" : 111
}

Nagłówek Location będzie zawierał adres URL utworzonego obiektu, np. https://api.monit24.pl/v3/services/111.

Modyfikacja obiektów

Istniejące obiekty można modyfikować za pomocą zapytań PUT wykonywanych na adresie URL obiektu. Treść takiego zapytania powinna zawierać obiekt JSON, którego pola są podzbiorem pól zmienianego obiektu. W szczególności obiekt ten może zawierać wszystkie pola (zawsze możliwe jest więc "odesłanie" w PUT wyniku GET w niezmienionej postaci) lub tylko te, które chcemy zmodyfikować. Jeśli zmiana wartości któregoś z pól (np. identyfikatora) nie jest dozwolona, to w przypadku wysłania innej wartości niż obecna, API odpowie błędem field_is_immutable.

Przykładowo: użytkownik ma dostęp do następującej grupy usług:

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

{
   "assigned_sensor_ids" : {
       "default" : [1, 2],
       "ipv6" : [2],
       "mobile" : [5, 6],
       "webappcheck" : [3, 4],
   },
   "id" : 2000,
   "is_default" : true,
   "periodic_daily_reports" : true,
   "periodic_monthly_reports" : true,
   "periodic_weekly_reports" : true,
   "name" : "Default group",
   "owner_id" : 300,
   "sensor_ids" : [
      1,
      2
   ]
}

Może wówczas zmienić jej nazwę i przypisane stacje monitorujące za pomocą wywołania:

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" : 2000,
   "is_default" : true,
   "periodic_daily_reports" : true,
   "periodic_monthly_reports" : true,
   "periodic_weekly_reports" : true,
   "name" : "Grupa domyślna",
   "owner_id" : 300,
   "sensor_ids" : [
      1,
      2
   ]
}' 'https://api.monit24.pl/v3/groups/2000'

W tym przypadku identyczny efekt można było uzyskać wysyłając jedynie zmieniane pola:

curl -u USERNAME:PASSWORD -X PUT -H 'Content-Type: application/json' \
   -d '{
   "name" : "Grupa domyślna",
   "assigned_sensor_ids" : {
       "default" : [1, 2],
       "ipv6" : [3],
       "mobile" : [6],
       "webappcheck" : [4, 5],
   }
}' 'https://api.monit24.pl/v3/groups/2000'

Próba wysłania innej wartości niż 300 w polu owner_id zakończy się błędem field_is_immutable (podobnie dla pól is_default oraz id).

Wywołanie metody PUT na obiekcie wymaga uprawnienia update. Poprawna modyfikacja obiektu jest sygnalizowana kodem HTTP 204 No Content.

Usuwanie obiektów

Do usuwania obiektów służy metoda HTTP DELETE. Nie wymaga podawania innych parametrów poza adresem URL usuwanego obiektu, zwraca kod 204 No Content w przypadku poprawnego usunięcia obiektu.

Przykład: aby usunąć grupę usług o identyfikatorze 2000, wywołujemy:

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

Usunięcie obiektu wymaga posiadania uprawnienia delete do tego obiektu.