Przewodnik po integracji z API

Lither udostępnia REST API, dzięki któremu możesz połączyć własne systemy z danymi floty, agentami AI, automatyzacją procesów i rejestrami operacyjnymi. Ten przewodnik omawia pojęcia potrzebne do pewnej integracji: uwierzytelnianie, punkty końcowe, zdarzenia w czasie rzeczywistym, paginację, obsługę błędów oraz bezpieczeństwo. Po dokładne ścieżki punktów końcowych, nazwy pól i aktualne limity zawsze traktuj oficjalną dokumentację jako źródło prawdy.

Uwierzytelnianie i klucze API

Dostęp do API uzyskuje się za pomocą kluczy API, które generujesz i którymi zarządzasz w swoim obszarze roboczym. Klucz identyfikuje Twoją integrację i upoważnia ją do działania w Twoim imieniu, dlatego traktuj go jak hasło. Typowy wzorzec żądania REST polega na przekazaniu klucza w nagłówku HTTP. Wyłącznie jako przykład poglądowy, żądanie zwykle zawiera nagłówek autoryzacji w postaci Authorization: Bearer YOUR_API_KEY. Dokładny nagłówek i wywoływany adres URL znajdziesz w dokumentacji.

Klucze są ograniczane zakresem za pomocą kontroli dostępu opartej na rolach, więc integracja otrzymuje tylko te uprawnienia, których faktycznie potrzebuje. Tworząc klucz do wąskiego zadania, nadaj mu minimalny wymagany zakres zamiast pełnego dostępu do konta. Więcej o działaniu zakresów znajdziesz na stronach RBAC oraz API Connections.

Praca z punktami końcowymi

API stosuje standardowe konwencje REST. Zasoby są adresowane przez adres URL, działasz na nich czasownikami HTTP, takimi jak GET do odczytu, POST do tworzenia, PATCH lub PUT do aktualizacji oraz DELETE do usuwania, a treści żądań i odpowiedzi są kodowane w formacie JSON. Wysyłając treść, ustaw nagłówek Content-Type: application/json.

Dobrym pierwszym krokiem jest wykonanie pojedynczego uwierzytelnionego żądania odczytu i potwierdzenie, że otrzymujesz poprawną odpowiedź JSON oraz status 200. Następnie możesz dopasować potrzebne zasoby do swojego przypadku użycia. Pełny katalog dostępnych zasobów znajduje się w przeglądzie Endpoints i jest szczegółowo opisany w dokumentacji, łącznie z dokładnymi ścieżkami i polami zwracanymi przez każdy zasób.

Webhooki kontra odpytywanie

Gdy Twoja integracja musi reagować na coś, co dzieje się wewnątrz Lither, masz dwie główne możliwości.

• Odpytywanie (polling) oznacza, że Twój system wywołuje punkt końcowy według harmonogramu i sprawdza, czy coś się zmieniło. Jest proste w budowie i działa wszędzie, ale wprowadza opóźnienie i marnuje żądania, gdy nic się nie zmieniło.
• Webhooki odwracają kierunek: Lither wysyła żądanie HTTP na kontrolowany przez Ciebie adres URL w chwili wystąpienia zdarzenia. Jest to wydajniejsze i bliższe czasowi rzeczywistemu, kosztem utrzymywania punktu końcowego zdolnego odbierać i weryfikować przychodzące wywołania.

Z reguły wybieraj webhooki do pracy sterowanej zdarzeniami, takiej jak zmiany statusu i zakończenia zadań, a do odpytywania sięgaj tylko tam, gdzie webhook jest niedostępny lub Twoje środowisko nie może przyjmować ruchu przychodzącego. Zadbaj, aby obsługa webhooka była idempotentna, ponieważ to samo zdarzenie może zostać dostarczone więcej niż raz, i zwracaj szybką odpowiedź o powodzeniu, aby nadawca niepotrzebnie nie ponawiał próby. Zobacz Webhooks oraz głębsze porównanie w webhooki kontra odpytywanie.

Limity zapytań, paginacja i obsługa błędów

Jak większość produkcyjnych API, Lither stosuje limity zapytań, aby utrzymać stabilność platformy dla wszystkich. Konkretne limity znajdują się w dokumentacji, lecz dobre praktyki są uniwersalne. Odczytuj informacje o limitach zwracane w nagłówkach odpowiedzi, wycofuj się po osiągnięciu limitu zamiast ponawiać natychmiast i stosuj wykładnicze wycofywanie z losowym odstępem, aby wielu klientów nie ponawiało prób równocześnie. Wskazówki branżowe szeroko zalecają grupowanie pracy w paczki oraz buforowanie odpowiedzi, które można ponownie wykorzystać, by komfortowo pozostać poniżej limitu.

Punkty końcowe zwracające listy oddają wyniki w stronach, a nie wszystkie naraz. Zawsze stosuj mechanizm paginacji opisany w dokumentacji zamiast zakładać stały rozmiar strony i pobieraj kolejne strony, aż żadna nie pozostanie. Nigdy nie wpisuj na sztywno liczby całkowitej wyników.

W obsłudze błędów opieraj się na kodach statusu HTTP: 2xx oznacza powodzenie, 4xx oznacza żądanie wymagające poprawy, na przykład brakujące pole lub nieprawidłowy klucz, a 5xx oznacza problem po stronie serwera, który można bezpiecznie ponowić z wycofaniem. Odczytuj treść błędu JSON, aby poznać maszynowo czytelny powód, rejestruj ją i przekazuj użytkownikom czytelny komunikat zamiast cicho zawodzić.

Najlepsze praktyki bezpieczeństwa

Traktuj klucze API jak sekrety. Przechowuj je w zmiennych środowiskowych lub menedżerze sekretów, nigdy w kodzie po stronie klienta, w systemie kontroli wersji ani w logach. Zawsze wywołuj API przez HTTPS, aby poświadczenia i dane były szyfrowane podczas przesyłania. Używaj osobnych kluczy dla różnych integracji i środowisk, aby móc unieważnić jeden bez psucia pozostałych, i okresowo rotuj klucze.

Odbierając webhooki, zweryfikuj, że każde żądanie rzeczywiście pochodzi z Lither, zanim na nie zareagujesz, i przyjmuj wyłącznie wywołania przez HTTPS. Ponieważ Lither jest hostowany w UE, ściśle ograniczaj zakres kluczy i żądaj tylko tych danych, których integracja potrzebuje, co zmniejsza ślad przetwarzania i wspiera Twoje obowiązki zgodności. Gotowy, aby zacząć? Załóż konto i otwórz dokumentację lub skontaktuj się z nami, jeśli potrzebujesz pomocy w zaplanowaniu integracji.