Co nowego w API 3?

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.

Zgodność

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.

Zakres

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.

Wydajność

W API 3 zastosowaliśmy szereg rozwiązań mających na celu zwiększenie wydajności:

nowa architektura sprzętowa oraz programowa (serwer WWW),
ulepszone mechanizmy wewnętrznego cache'owania danych na wielu poziomach,
niektóre krytyczne dla wydajności fragmenty przepisane od zera w języku programowania niższego poziomu niż reszta kodu,
obsługa cache'owania wyników przez przeglądarki, dzięki zastosowaniu mechanizmów standardowo dostępnych w protokole HTTP,
ulepszone mechanizmy obsługi sesji, zarządzania połączeniami z bazą danych, pobierania plików HAR i inne,
wprowadzone mechanizmy optymalizujące przetwarzanie zapytań w zależności od pobieranych pól, czy dowiązywanych obiektów.

Dzięki nim niektóre wywołania operacji API są nawet kilkukrotnie szybsze niż ich odpowiedniki w poprzedniej wersji.

Prostota

API 3 upraszcza niektóre kwestie związane z samym interfejsem. Przykładowo:

Dostępne możliwości dowiązywania obiektów (teraz "embed", wcześniej "with") nie zależą od tego, czy pobieramy jeden obiekt ("Read" w API 2.0), czy całą listę ("Find").
W operacji aktualizującej obiekty można użyć dokładnie takich samych pól, które są zwracane w wyniku operacji pobierającej obiekt ("odesłać go w całości"), nawet jeśli zmiana wartości niektówych pól nie jest dozwolona - w tym ostatnim przypadku można odesłać tylko taką samą wartość pola, jaką wcześniej pobrano.

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).

Podsumowanie

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.