API (interfejs programowania aplikacji) umożliwia klientom integrację systemu zarządzania flotą (FMS) ze swoimi systemami oraz pobieranie i przesyłanie danych o różnych podmiotach.
Klient wysyła żądania HTTP do systemu, podając informacje o zamierzonym działaniu. Polecenia HTTP zazwyczaj stosowane w interfejsie API:
- GET – odczyt zasobu;
- POST– zmiana stanu zasobu;
Żądana zawartość jest dostarczana w formacie JSON z kodowaniem UTF-8. W przypadku zastosowania innego formatu, jest to określone w opisie metody.
Kod statusu HTTP to identyfikator statusu żądania – w przypadku akceptacji żądania zwracany kod to 200. Wraz z tą odpowiedzią otrzymywane są żądane informacje z serwera. Takie odpowiedzi będą się różnić, w zależności od typu wykorzystywanego interfejsu API. Odpowiedzi interfejsu API dla różnych typów API opisano w odpowiednich rozdziałach.
W przypadku wystąpienia błędu wysłanego żądania, system odpowie komunikatem zwrotnym zawierającym kod statusu. Typowe kody błędów:
- Kod 400 – Bad request (nieprawidłowe żądanie) – żądanie API nie zostało rozpoznane.
- Kod 401 – Unauthorized (nieouprawnione) – oznacza, że brakuje poświadczeń uwierzytelniających lub są one niepoprawne;
- Kod 403 – Forbidden (zabronione) – oznacza, że klient nie ma uprawnień dostępu do żądanego zasobu lub wykonania żądanego działania;
- Kod 404 – Not found (nie odnaleziono) – oznacza, że żądany zasób nie został odnaleziony.
- Code 500 – Internal server error – błąd wewnętrzny serwera, skontaktuj się z pomocą techniczną dostawcy.
Kody błędów dostarczają ogólnych informacji o rodzaju błędu, umożliwiając użytkownikowi identyfikację źródła problemu.
Niektóre interfejsy API posiadają w swoich komunikatach zwrotnych opcjonalne elementy (parametry), które system może z różnych powodów pomijać (brak danych, złe dane, czas odpowiedzi itp.). Użytkownik nie może zakładać, że komunikat zwrotny będzie zawsze zawierać określone dane opcjonalne.
Ograniczenia interfejsu API
Wszystkie interfejsy API mają jedno ograniczenie:
- Maksymalna liczba przetwarzanych żądań to 1000 na minutę.
To ograniczenie dotyczy wszystkich istniejących interfejsów API systemu zarządzania flotą (FMS).
Uwierzytelnianie API
Uwierzytelnianie i autoryzacja API są konieczne do kontrolowania wykorzystania interfejsów API przez poszczególnych klientów oraz ich integracji z różnymi systemami. Aby wysyłać autoryzowane żądania do systemowych interfejsów API, aplikacja wysyłająca zapytania musi w imieniu użytkownika systemu uzyskać klucz API API_key.
Jedynym sposobem na uzyskanie klucza API przez klientów jest bezpośredni kontakt z działem wsparcia technicznego dostawcy usług. Klucz API składa się z losowo generowanych liter, cyfr i symboli.
Przykład żądania wykorzystującego klucz_API:
Jeśli klucz interfejsu API wygasł, został usunięty lub po prostu wyłączony, system zwróci następującą odpowiedź:
Punkty końcowe interfejsu API, parametry żądania i komunikaty zwrotne można przeglądać przy pomocy edytora „Swagger” za pośrednictwem: https://api.fm-track.com
Uwaga
Wszystkie typy API wymagają określenia wersji interfejsu API.
Ważne!
W związku z ciągłym rozwojem zarówno interfejsu API, jak i systemu z którego pobiera on informacje, użytkownicy mogą niekiedy otrzymywać parametry niewymienione w opisach. Nieznane parametry, nieudokumentowane w opisach poszczególnych interfejsów API, zaleca się po prostu ignorować.
Wersjonowanie i zgodność
W związku z tym, że rozwiązanie API jest stale aktualizowane, ulepszane i odpowiednio modyfikowane, konieczne jest wyjaśnienie pojęcia „Zgodności” i tego, jak wpływa na ona użytkowanie interfejsu API.
Po aktualizacji interfejsu API następuje jedna z dwóch poniższychopcji:
- Interfejs API jest wstecznie kompatybilny – oznacza to, że wprowadzone zmiany w żaden sposób nie wpłyną na funkcjonowanie interfejsu API i tym samym nie powstanie nowa wersja.
- Interfejs API nie jest kompatybilny wstecz – oznacza to, że sposób funkcjonowania niektórych komponentów interfejsu API został zmieniony. W takim wypadku publikowana jest nowa wersja interfejsu API.
Wersja interfejsu API może zostać uznana za wstecznie kompatybilną, jeśli:
- Dodano nowy zasób API.
- Do istniejącego interfejsu API dodano nowe parametry opcjonalne żądania.
- Do istniejących komunikatów zwrotnych API dodano nowe parametry żądania.
- W istniejących komunikatach zwrotnych interfejsu API zmieniono kolejność właściwości.
- Zmiana długości lub formatu identyfikatorów obiektów lub inne nieprzejrzyste ciągi.
Można bezpiecznie zakładać, że identyfikatory obiektów generowane przez system nie będą przekraczać 255 znaków, natomiast użytkownik powinien być w stanie obsługiwać identyfikatory o potencjalnej długości 255 znaków. Na przykład, gdy użytkownik wykorzystuje MySQL, identyfikatory powinny być przechowywane w kolumnie VARCHAR (255) COLLATE utf8_bin (konfiguracja COLLATE zapewnia rozróżnianie wielkości liter w wyszukiwaniu). - Dodanie nowych wyliczeniowych typów danych (ENUM). – każdy system powinien bez większych problemów obsługiwać wszelkie nieznane typy danych ENUM. Na przykład, zmiana zestawu typów z [Prywatne, Biznesowe] na [Prywatne, Praca, Biznes], nie powinna mieć żadnego wpływu na system.