Ten dokument zawiera nieformalny opis kluczowych różnic pomiędzy aktualną wersją API a poprzednią "dużą" wersją (2.0). Jest przeznaczony głównie dla użytkowników korzystających wcześniej z API 2.
API 3, w odróżnieniu od swojego poprzednika, w większym stopniu polega na istniejących standardach i konwencjach, zamiast tworzyć własne:
Adresy URL
API 3 operuje na zasobach posiadających swoje własne adresy URL. W API 2 wszystkie zapytania były wysyłane na ten sam adres URL. Dzięki tej zmianie łatwiej można zorientować się w tym, co dane wywołanie robi bez szczegółowej analizy przesyłanej treści.
Metody HTTP
API 3 wykorzystuje metody GET
, HEAD
, POST
, PUT
oraz DELETE
,
w przeciwieństwie do API 2, które wykorzystywało jedynie metodę POST
.
Jest to zgodne z semantyką protokołu HTTP, mówiącą np. że wywołania, które nie zmieniają stanu po stronie serwera, powinny być obsługiwane metodą GET.
Nagłówki HTTP
Metadane są zwracane w nagłówkach HTTP (np. liczba obiektów w nagłówku X-Total-Count
),
dzięki czemu unikamy opakowywania wyników w dodatkową warstwę abstrakcji.
Statusy HTTP
API 3 zwraca błąd HTTP w przypadku błędu wywołania, zamiast statusu 200 OK z informacją o błędzie zaszytą w treści odpowiedzi (bardziej szczegółowe informacje wciąż są dostępne w treści). Dzięki temu łatwiej odróżnić zapytania błędne od poprawnych.
JSON
API 3 nie wspiera wywołań SOAP, ani serializacji XML. Główną motywacją była znacznie zwiększona wydajność i niezgodność SOAP-a z powyżej wyszczególnionymi pożytecznymi efektami wykorzystania protokołu HTTP (w przeciwieństwie do "tunelowania się przez niego"), a także prostota i łatwość (wręcz naturalność) mapowania formatu JSON na struktury danych występujące w olbrzymiej większości języków programowania: tablice (listy, krotki) i obiekty (rekordy, tablice asocjacyjne, mapy, hasze). Problemy z SOAP-em dość dobrze podsumowuje ta anegdota.
OpenAPI
Specyfikacja API 3 jest dostępna w formacie OpenAPI (Swagger), który zastąpił własny format specyfikacji ("Meta") z API 2. Zapewnia to zgodność i łatwość integracji z wieloma istniejącymi narzędziami. Na przykład nasza interaktywna dokumentacja API jest generowana przez narzędzie Swagger UI.
OAuth2
Mechanizm autentykacji wykorzystywany w API 3, zastępujący własny sposób logowania i obsługi sesji w API 2. Alternatywnie dostępna jest także prosta autentykacja za pomocą znanego i lubianego HTTP Basic Auth lub zarządzanie tokenami sesji za pomocą zasobów API.
API 3 jest znacznie bardziej kompletne od swojego poprzednika, tzn. udostępnia więcej operacji (np. wybrane modyfikacje wielu zasobów jednocześnie lub narzędzia diagnostyczne stacji monitorujących), mających większe możliwości (np. ograniczanie pól wyniku). Ogólna zasada jest następująca: jeśli coś da się zrobić w Panelu Administracyjnym, to da się to zrobić w API. Jeśli jednak się nie da, to jest to prawdopodobnie błąd w API - w takim przypadku prosimy o kontakt z Biurem Obsługi Klienta.
W API 3 zastosowaliśmy szereg rozwiązań mających na celu zwiększenie wydajności:
Dzięki nim niektóre wywołania operacji API są nawet kilkukrotnie szybsze niż ich odpowiedniki w poprzedniej wersji.
API 3 upraszcza niektóre kwestie związane z samym interfejsem. Przykładowo:
Dzięki większej zgodności z istniejącymi standardami wywołania są bardziej intuicyjne. Na przykład
curl 'https://api.monit24.pl/v3/sensors'
zamiast
curl -X POST -H 'Content-Type: application/json' -d '{"module":"Location","method":"Find","data":{}}' \ 'https://api.cloudmonit.pl/2.0.0/json_api'
(a i tak w tym drugim przypadku wyniki są dopiero w polu data.elements
wyniku).
Mamy nadzieję, że praca z API 3 będzie bardziej intuicyjna i przyjemna niż z jego poprzednią wersją. Szczegółowe informacje dotyczące migracji z API 2 znajdują się tutaj.