Ten dokument zawiera listę wskazówek dotyczących migracji z poprzedniej wersji API, 2.0, do aktualnej wersji (API 3).
Wysokopoziomowy opis różnic pomiędzy API 2.0 a API 3 znajduje się w tym miejscu.
Niektóre z nazw metod API 2.0 miały szczególne znaczenie. Ich odpowiedniki w API 3 są opisane na liście standardowych operacji API:
with
został zastąpiony przez dowiązywanie obiektów,X-Total-Count
,Sposób autentykacji, obsługa sesji, schemat wersjonowania API, obsługa błędów itp. są opisane na liście konwencji stosowanych w API.
API 3 nie udostępnia interfejsu SOAP ani XML, jedynie JSON.
API 3 nie jest podzielone na moduły. Składa się z zestawu udostępnianych operacji, z których każda określa metodę HTTP, adres URL wywołania, dostępne parametry i schemat przesyłanej treści. Operacje są oznaczane tagami mającymi na celu łatwiejsze ich wyszukiwanie; tagi są widoczne na najwyższym poziomie interaktywnej dokumentacji. Operacja może być oznaczona więcej niż jednym tagiem.
Inaczej niż w wersji 2.0, API 3 wykorzystuje JSON-owe wartości true
i false
(w poprzedniej wersji były zamiast nich używane liczby 1 i 0).
API 3 domyślnie wykorzystuje format zapisu daty i czasu zdefiniowany w RFC 3339 zamiast timestampów uniksowych występujących w 2.0.
W dalszej części dokumentu opisano, w kolejności alfabetycznej, szczegółowe instrukcje i odpowiedniki dla każdego z modułów i każdej metody API 2 (jeśli takie odpowiedniki istnieją).
Konta użytkowników są zwracane w inny sposób w API administracyjnym (/admin/accounts
) i klienckim (/accounts
).
W API administracyjnym obiekty kont są złączone z danymi właściciela konta (user_data
, obiekty User w API 2).
Limity konta są zawarte w przypisanym mu pakiecie (obiekcie package
).
Pola obiektu Account w API 2 odpowiadają następującym polom obiektów kont w API 3:
activated
- is_activated
(true
lub false
zamiast 0 lub 1),available_intervals
- niedostępne, można tworzyć usługi o dowolnym interval
nie mniejszym niż określony w pakiecie konta,blocked
- is_blocked
(true
lub false
zamiast 0 lub 1),id
- bez zmian,max_locations_limit
- package.maximum_sensors
(wymaga dowiązania pakietu),max_services
- package.maximum_services
(wymaga dowiązania pakietu),max_sms_numbers
- package.maximum_sms_numbers
(wymaga dowiązania pakietu),min_interval
- package.minimum_interval
(wymaga dowiązania pakietu),min_locations_limit
- niedostępne, jedynym warunkiem jest ustawienie przynajmniej jednej stacji monitorującej w grupie,name
- bez zmian,notification_channels
- package.available_notification_channel_ids
(wymaga dowiązania pakietu),package_id
- bez zmian,service_types
- package.available_service_types
(wymaga dowiązania pakietu).Aktywacja konta nie jest dostępna jako operacja administracyjna, odbywa się poprzez kliknięcie odnośnika w wiadomości e-mail wysyłanej przy rejestracji.
Konta utworzone przez administratorów oraz konta dodatkowych użytkowników istniejących kont nie wymagają aktywacji.
Jako administrator: POST /admin/accounts/{_id}/block
Rejestracja konta (nie wymaga autentykacji, na podany adres zostanie wysłany link aktywacyjny): POST /accounts/register
Utworzenie aktywnego konta dodatkowego użytkownika z dostępem do wszystkich usług na koncie głównym (być może read-only), ale bez możliwości tworzenia własnych usług: POST /accounts
Utworzenie aktywnego konta głównego z wybranym pakietem (jako administrator): POST /admin/accounts
Jako administrator: DELETE /admin/accounts/{_id}
Jako administrator: GET /admin/accounts
lub (zaawansowane) POST /admin/accounts/search
Jako użytkownik: GET /accounts
lub (zaawansowane) POST /accounts/search
Uwaga: wynik może być inny niż w wersji 2.0, gdyż nowa wersja API obsługuje mechanizm udostępniania grup.
Odpowiedniki metod Meta nie są dostępne w API 3. Do pobrania dostępna jest specyfikacja OpenAPI w formacie JSON.
Jako administrator: GET /admin/accounts/{_id}
Jako użytkownik: GET /accounts/{_id}
Pobranie własnego konta (jako użytkownik): GET /accounts/my_account
Pobranie konta, do którego należy wybrana grupa: GET /groups/{_id}/owner
Pobranie konta, do którego należy wybrana usługa: GET /services/{_id}/owner
Pobranie konta, do którego należy wybrany adres powiadomień: GET /notification_addresses/{_id}/owner
Pobranie konta, do którego należy wybrany adres raportów okresowych: GET /periodic_report_addresses/{_id}/owner
Jako administrator: POST /admin/accounts/{_id}/unblock
Jako użytkownik: PUT /accounts/{_id}
Jako administrator: PUT /admin/accounts/{_id}
API 3 nie udostępnia odpowiedników operacji do zarządzania kontem dystrybucyjnym.
Administratorzy dystrybucji mają dostęp do API administracyjnego (operacje na zasobach /admin/...
), umożliwiającego zarządzanie kontami i pakietami w dystrybucji.
Operacja niedostępna w API 3. Jeśli jesteś zainteresowany/a współpracą partnerską z Monit24.pl, skontaktuj się z nami.
Operacja niedostępna w API 3.
Odpowiedniki metod Meta nie są dostępne w API 3. Do pobrania dostępna jest specyfikacja OpenAPI w formacie JSON.
Operacja niedostępna w API 3.
Operacja niedostępna w API 3.
Lista błędów monitoringu jest publicznie dostępna, podobnie jak w wersji 2.0.
Odpowiedniki pól obiektu Error z API 2 (zasób error_types
):
comments
- extra_info
,description
- bez zmian,diagnosis
- bez zmian,id
- bez zmian,name
- bez zmian.GET /error_types
lub (zaawansowane) POST /error_types/search
Odpowiedniki metod Meta nie są dostępne w API 3. Do pobrania dostępna jest specyfikacja OpenAPI w formacie JSON.
GET /error_types/{_id}
Pola grup odpowiadające polom obiektów Group z API 2.0:
account_id
- owner_id
,daily_reports
- periodic_daily_reports
(true
lub false
zamiast 0 lub 1),default
- is_default
(true
lub false
zamiast 0 lub 1),language
- zmiana języka raportów i powiadomień nie jest dostępna dla grup,location_ids
- sensor_ids
,monthly_reports
- periodic_monthly_reports
(true
lub false
zamiast 0 lub 1),name
- bez zmian,weekly_reports
- periodic_weekly_reports
(true
lub false
zamiast 0 lub 1),POST /groups
DELETE /groups/{_id}
GET /groups
lub (zaawansowane) POST /groups/search
Pobranie grup należących do wybranego konta: GET /accounts/{_id}/groups
Pobranie grup należących do własnego konta: GET /accounts/my_account/groups
Pobranie grup, do których możemy przenieść wybraną usługę: GET /services/{_id}/available_groups
GET /groups/{_id}/sensors
lub poprzez dowiązanie listy stacji monitorujących do grupy.
Odpowiedniki metod Meta nie są dostępne w API 3. Do pobrania dostępna jest specyfikacja OpenAPI w formacie JSON.
GET /groups/{_id}
Pobranie grupy domyślnej wybranego konta: GET /accounts/{_id}/default_group
Pobranie własnej grupy domyślnej: GET /groups/my_default_group
Pobranie grupy, do której należy wybrana usługa: GET /services/{_id}/group
Pobranie grupy, do której należy wybrany adres powiadomień: GET /notification_addresses/{_id}/group
Pobranie grupy, do której należy wybrany adres raportów okresowych: GET /periodic_report_addresses/{_id}/group
Operacja niedostępna w API 3. Należy zmodyfikować pobraną wartość atrybutu sensor_ids
grupy według uznania, a następnie odesłać ją w PUT /groups/{_id}
.
Operacja niedostępna w API 3. Należy zmodyfikować pobraną wartość atrybutu sensor_ids
grupy według uznania, a następnie odesłać ją w PUT /groups/{_id}
.
PUT /groups/{_id}
Podobnie jak w wersji 2.0, lista stacji monitorujących jest publicznie dostępna.
Stacje monitorujące zmieniły nazwę z "Location" na "sensor". Odpowiedniki pól obiektu Location z wersji 2.0:
city
- bez zmian,color
- niedostępne; w nowej wersji API stacje monitorujące nie mają przypisanych "oficjalnych" kolorów,country
- bez zmian,id
- bez zmian,ip
- ip_address
,is_available
- bez zmian, ale przyjmuje wartość true
lub false
zamiast 0 lub 1,link
- links
,name
- bez zmian,GET /sensors
lub (zaawansowane) POST /sensors/search
Pobranie listy stacji przypisanych do grupy: GET /groups/{_id}/sensors
Pobranie listy stacji, z których wybrana usługa jest monitorowana: GET /services/{_id}/monitoring_sensors
Odpowiedniki metod Meta nie są dostępne w API 3. Do pobrania dostępna jest specyfikacja OpenAPI w formacie JSON.
GET /sensors/{_id}
W API 3 jedynym odpowiednikiem modułu Meta (publicznych informacji o samym API) jest statyczny dokument specyfikacji OpenAPI w formacie JSON.
Lista błędów, które może zwracać każda z operacji, jest dostępna w specyfikacji OpenAPI oraz w interaktywnej dokumentacji.
Odpowiedniki metod Meta nie są dostępne w API 3. Do pobrania dostępna jest specyfikacja OpenAPI w formacie JSON.
API 3 nie jest podzielone na moduły, więc nie posiada odpowiednika tej metody.
Adresy powiadomień działają podobnie jak w API 2.0. Odpowiedniki pól obiektów NotificationAddress:
address
- bez zmian,group_id
- bez zmian,id
- bez zmian,notification_channel
- notification_channel_id
, email_long
zmienił nazwę na email
.POST /notification_addresses
DELETE /notification_addresses/{_id}
GET /notification_addresses
lub (zaawansowane) POST /notification_addresses/search
Adresy należące do wybranego konta: GET /accounts/{_id}/notification_addresses
Adresy przypisane do wybranej grupy: GET /groups/{_id}/notification_addresses
Adresy włączone dla wybranej usługi: GET /services/{_id}/notification_addresses
Odpowiedniki metod Meta nie są dostępne w API 3. Do pobrania dostępna jest specyfikacja OpenAPI w formacie JSON.
GET /notification_addresses/{_id}
PUT /notification_addresses/{_id}
Pakiety są obsługiwane inaczej w API użytkownika i w API administracyjnym. Pola obiektu Package z API 2.0:
available_intervals
- niedostępne, pakiet umożliwia tworzenie usług z dowolnym odstępem pomiędzy sprawdzeniami nie mniejszym niż minimum_interval
,id
- bez zmian,max_locations_limit
- maximum_sensors
,max_services
- maximum_services
,max_sms_numbers
- maximum_sms_numbers
,min_interval
- minimum_interval
,min_locations_limit
- niedostępne, jedynym warunkiem jest ustawienie przynajmniej jednej stacji monitorującej w grupie,name
- bez zmian,notification_channels
- available_notification_channel_ids
,service_types
- available_service_types
.Jako użytkownik: GET /packages
lub (zaawansowane) POST /packages/search
Jako administrator: GET /admin/packages
lub (zaawansowane) POST /admin/packages/search
Odpowiedniki metod Meta nie są dostępne w API 3. Do pobrania dostępna jest specyfikacja OpenAPI w formacie JSON.
Jako użytkownik: GET /packages/{_id}
Jako administrator: GET /admin/packages/{_id}
Pobranie pakietu wybranego konta (jako użytkownik): GET /accounts/{_id}/package
Pobranie własnego pakietu (jako użytkownik): GET /packages/my_package
Odpowiednikiem raportów okresowych z API 2.0 są obiekty periodic_report_addresses
.
Pola obiektów ReportAddress:
address
- bez zmian,group_id
- bez zmian,id
- bez zmian,report_type
- report_frequency
.POST /periodic_report_addresses
DELETE /periodic_report_addresses/{_id}
GET /periodic_report_addresses
lub (zaawansowane) POST /periodic_report_addresses/search
Lista adresów raportów w wybranej grupie: GET /groups/{_id}/periodic_report_addresses
Lista adresów raportów należących do wybranego konta: GET /accounts/{_id}/periodic_report_addresses
Lista adresów, na które będą wysyłane raporty dla wybranej usługi: GET /services/{_id}/periodic_report_addresses
Odpowiedniki metod Meta nie są dostępne w API 3. Do pobrania dostępna jest specyfikacja OpenAPI w formacie JSON.
GET /periodic_report_addresses/{_id}
PUT /periodic_report_addresses/{_id}
Pola obiektów Service z API 2.0 i odpowiadające im pola usług i ich aktualnych statusów w API 3:
avg_response_time
- niedostępne; dla pojedynczej usługi można pobrać identyfikator ostatniej wykonanej analizy dowiązując status.last_analysis_id
, a następnie uśrednić czasy odpowiedzi ze sprawdzeń wchodzących w jej skład (GET /services/{_id}/history/analyses/{_analysis_id}/checks
),daily_silent_mode_hours
- silent_hours
, napis złożony z 24 znaków 0 lub 1 zamiast tablicy 24 wartości typu boolean,description
- bez zmian,error
- status.check_status == "failure"
(wymaga dowiązania status
),features
- extended_settings
, format zmieniony z tablicy obiektów klucz-wartość na pojedynczy obiekt,group_id
- bez zmian,id
- bez zmian,interval
- bez zmian, ale może zostać ustawiony dowolny nie mniejszy niż limit określony w pakiecie,last_invalid_check
- status.last_failure_analysis_time
(RFC 3339 zamiast timestampa uniksowego, wymaga dowiązania status
),last_valid_check
- status.last_ok_analysis_time
(RFC 3339 zamiast timestampa uniksowego, wymaga dowiązania status
),locations_status
- niedostępne; dla pojedynczej usługi można pobrać sprawdzenia wchodzące w skład ostatniej wykonanej analizy za pomocą zapytania GET /services/{_id}/history/analyses/last_analysis/checks
,name
- bez zmian,notification_channels
- notification_channel_ids
,notification_conditions
- notification_condition_ids
, wartość bad
zmieniona na failure
, ok
na recovery
, still_bad
na failure_continuation
, a still_bad_after_silent_mode
na silent_failure
,notification_delay
- niedostępne w API 3,notification_mode
- notification_mode_id
, wartość immediately
zmieniona na default
, wartości after_X_minutes
zmienione na after_X_minutes_failure
,pause
- negacja is_active
(true
lub false
zamiast 0 lub 1),silent_mode
- status.notifications_status == "silent"
(wymaga dowiązania status
),status
- status.summary
(wymaga dowiązania status
):
status_text
- niedostępne w API 3,suspension
- status.monitoring_status == "suspended"
(wymaga dowiązania status
),type_id
- w API 3 typy mają identyfikatory tekstowe (symbole, np. "http"),type_name
- type.name
(wymaga dowiązania type
),type_prefix
- type.address_prefix
(wymaga dowiązania type
),url
- address
,weekly_suspension_hours
- suspension_hours
, napis złożony z 168 znaków 0 lub 1 zamiast tablicy 168 wartości typu boolean.POST /services
DELETE /services/{_id}
GET /services
lub (zaawansowane) POST /services/search
Pobranie usług należących do wybranego konta: GET /accounts/{_id}/services
Pobranie własnych usług: GET /accounts/my_account/services
Pobranie usług należących do wybranej grupy: GET /groups/{_id}/services
Pobranie usług należących do własnej grupy domyślnej: GET /groups/my_default_group/services
Odpowiedniki metod Meta nie są dostępne w API 3. Do pobrania dostępna jest specyfikacja OpenAPI w formacie JSON.
GET /services/{_id}
Pobranie usługi do której jest przypisane wybrane zaplanowane zawieszenie: GET /suspensions/{_id}/service
PUT /services/{_id}
Bezpośrednim odpowiednikiem obiektów ServiceSuspension z API 2.0 są obiekty suspensions
.
Zmiany w polach obiektów ServiceSuspension:
comment
- description
,end_timestamp
- end_time
(RFC 3339 zamiast timestampa uniksowego),id
- bez zmian,service_id
- bez zmian,start_timestamp
- start_time
(RFC 3339 zamiast timestampa uniksowego).POST /suspensions
DELETE /suspensions/{_id}
GET /suspensions
lub (zaawansowane) POST /suspensions/search
Pobranie listy zawieszeń dla wybranej usługi: GET /services/{_id}/suspensions
Odpowiedniki metod Meta nie są dostępne w API 3. Do pobrania dostępna jest specyfikacja OpenAPI w formacie JSON.
GET /suspensions/{_id}
Pola obiektów ServiceType z API 2.0 i odpowiadające im pola obieków service_types w API 3:
features
- dostępne poprzez dowiązanie tablicy extended_setting_formats
; odpowiedniki poszczególnych pól są następujące:
advanced
- niedostępne w API 3,default
- bez zmian,desc
- zmienione na description
,id
- zmienione na setting_id
; jednoznacznym identyfikatorem obiektu specyfikacji ustawienia jest para service_type_id
, setting_id
,interactor_specification.options
- zmienione na prostą tablicę enum
,interactor_specification.type
- zmienione na suggested_form_element
,max
- zmienione na maximum
,max_length
- zmienione na maximum_length
,min
- zmienione na minimum
,min_length
- zmienione na minimum_length
,nullable
- zmienione na is_nullable
,options
- zmienione na enum
,regex
- zmienione na pattern
,type
- nazwa pola bez zmian; dopuszczalne wartości: string
, integer
, number
, boolean
i regex
.id
- w API 3 typy usług identyfikowane są tekstowym symbolem,is_available
- niedostępne; aby pobrać listę dostępnych typów dla konta należy użyć operacji GET /accounts/{_id}/available_service_types
,name
- bez zmian,prefix
- addres_prefix
,quota
- niedostępne, limity usług dla konta można sprawdzić pobierając jego pakiet,used
- niedostępne, niewykorzystane limity usług poszczególnych typów można pobrać za pomocą operacji GET /accounts/{_id}/available_service_types
.GET /service_types
lub (zaawansowane) POST /service_types/search
Limity typów dla wybranego konta: GET /accounts/{_id}/available_service_types
Limity typów dla wybranej grupy (takie, jak dla konta, do którego należy grupa): GET /groups/{_id}/available_service_types
Odpowiedniki metod Meta nie są dostępne w API 3. Do pobrania dostępna jest specyfikacja OpenAPI w formacie JSON.
GET /service_types/{_id}
Typ wybranej usługi: GET /services/{_id}/type
Moduł Stats został podzielony na kilka grup operacji i znacznie poszerzony:
charts
- operacje zwracające dane do wykresów szybkości działania i dostępności,history
- operacje zwracające dane o historii monitoringu: analizy, sprawdzenia, treść strony z momentu awarii, pliki HAR, zmiany statusu usługi itp.,admin
- niektóre ze statystyk dostępnych dla administratora.Uwaga: Identyfikator analizy (analysis_id
) jest tym samym, co iteration_id
z API 2.0
Pobranie listy sprawdzeń dla wybranej usługi: GET /services/{_id}/history/checks
Uwaga: powyższa operacja zwraca wyniki z ograniczonego przedziału czasowego, z paginacją. Zapoznaj się z jej dokumentacją przed użyciem.
Uwaga 2: Statystyki z rozbiciem na fazy żądań dla sprawdzeń FullPage są dostępne jedynie w plikach HAR.
Pobranie listy sprawdzeń z wybranej analizy działania usługi: GET /services/{_id}/history/analyses/{_analysis_id}/checks
Pobranie listy błędnych sprawdzeń dla wybranej usługi: GET /services/{_id}/history/checks?result=error
Uwaga: powyższa operacja zwraca wyniki z ograniczonego przedziału czasowego, z paginacją. Zapoznaj się z jej dokumentacją przed użyciem.
Pobranie pliku HAR z wybranego sprawdzenia: GET /services/{_id}/history/analyses/{_analysis_id}/checks/{_sensor_id}/artifacts/har/plain
Pobranie listy sprawdzeń, dla których są dostępne pliki HAR: GET /services/{_id}/history/checks?har_available=true
Uwaga: powyższa operacja zwraca wyniki z ograniczonego przedziału czasowego, z paginacją. Zapoznaj się z jej dokumentacją przed użyciem.
Odpowiedniki metod Meta nie są dostępne w API 3. Do pobrania dostępna jest specyfikacja OpenAPI w formacie JSON.
Jako administrator: GET /admin/usage_stats/by_account/{year}/{month}
Jako administrator: GET /admin/usage_stats/by_group/{year}/{month}
GET /serivces/{_id}/charts/performance
Uwaga: operacja ta nie używa stałego zbioru interwałów, a zagregowane punkty nie muszą odpowiadać równym przedziałom czasowym.
GET /services/{_id}/history/service_level
Nie jest dostępne pobieranie danych dostępności dla wszystkich usług jednocześnie.
GET /services/{_id}/charts/availability?limit=1000
Operacja niedostępna w API 3.
Obiekty User zostały podzielone na accounts
(dane dostępne dla innych użytkowników, np. przy udostępnianiu) i user_data
(prywatne dane użytkownika).
Każde konto (account
) posiada stowarzyszony obiekt user_data
o tym samym identyfikatorze.
W API administracyjnym konta zawierają także pola user_data
.
Pola obiektów User z API 2.0:
account_id
- tożsame z account.id
oraz user_data.id
,address
- user_data.address
,contact_person
- user_data.contact_person
,contact_phone
- user_data.phone_numer
,email
- user_data.email_address
,id
- tożsame z account.id
oraz user_data.id
,language
- account.language_id
; identyfikator języka w słowniku languages
,last_login_ip
- niedostępne w API 3,last_login_timestamp
- niedostępne w API 3,login
- account.username
,tax_id
- user_data.tax_identification_number
.Niedostępne dla użytkownika. Możliwe jest pobranie jedynie listy kont.
Jako administrator informacje o użytkownikach można pobrać w ten sam sposób, co dane kont.
POST /auth_token
lub z użyciem OAuth2.
DELETE /auth_token
lub z użyciem OAuth2.
Odpowiedniki metod Meta nie są dostępne w API 3. Do pobrania dostępna jest specyfikacja OpenAPI w formacie JSON.
Pobranie danych wybranego użytkownika: GET /user_data/{_id}
Pobranie własnych danych: GET /user_data/my_user_data
Modyfikacja danych użytkownika: PUT /user_data/{_id}
Modyfikacja własnych danych: PUT /user_data/my_user_data