Paginacja API (cursor pagination)

Paginacja API to sposób, w jaki usługa dzieli długą listę wyników na mniejsze strony. Zamiast oddać tysiące kontaktów, zamówień lub dokumentów jednym wywołaniem, API zwraca fragment danych oraz informację, jak pobrać następny. W automatyzacji to warunek kompletności: bez paginacji workflow często pobiera pierwszą stronę i po cichu pomija całą resztę.

Dlaczego API nie zwraca wszystkiego naraz?

Duże odpowiedzi są wolniejsze, trudniejsze do przetworzenia i zwiększają ryzyko przekroczenia limitów albo timeoutu. Dlatego dokumentacje zwykle podają domyślną liczbę wyników na stronę i maksymalny rozmiar strony. Stripe dla wielu list używa parametrów limit oraz kursora starting_after albo ending_before. GitHub odsyła do kolejnej strony przez nagłówek Link. Wniosek jest ważniejszy niż konkretny format: mechanizm jest własnością danego API, więc nie można przenosić parametrów między usługami na pamięć.

Offset i cursor: dwa popularne modele

Paginacja offsetowa najczęściej używa numeru strony lub przesunięcia, na przykład page=3 albo offset=200. Jest prosta do zrozumienia, lecz może dawać niespójne wyniki, gdy w trakcie pobierania przybywają nowe rekordy albo zmienia się sortowanie. Paginacja kursorowa przekazuje znak miejsca w liście, zwykle identyfikator ostatniego rekordu lub nieprzezroczysty token zwrócony przez API. Jest lepsza dla rosnących zbiorów, ale nie należy samodzielnie odgadywać kursora. Trzeba użyć dokładnie wartości z odpowiedzi.

Co to zmienia dla systemu eksperta?

Przy synchronizacji CRM, pobieraniu transkrypcji, archiwizowaniu zakupów czy aktualizacji tagów pierwsza strona rzadko oznacza całość danych. Jeśli proces ma przygotować segment dla kampanii, a pobierze jedynie pierwsze 100 osób, decyzja oparta na tym wyniku będzie błędna. To samo dotyczy systemu AI karmionego historią klienta: niekompletny kontekst może wyglądać wiarygodnie, ale prowadzi do złego follow-upu. Paginacja jest więc elementem jakości danych, a nie technicznym detalem dla programistów.

Praktyczny wzorzec workflowu

Zacznij od pierwszego żądania z bezpiecznym rozmiarem strony. Zapisz rekordy, a potem sprawdź sygnał zakończenia wskazany przez dostawcę, na przykład has_more=false, brak linku rel="next" albo pustą kolejną stronę. Jeżeli dane jeszcze są, wyślij kolejne żądanie z kursosem lub numerem strony zwróconym przez API. Każdą stronę przetwarzaj tak, aby ponowne uruchomienie nie tworzyło duplikatów. Warto też zapisać ostatni poprawnie obsłużony kursor, aby po awarii wznowić pracę od właściwego miejsca.

Przykład: porządkowanie leadów po live

Wyobraź sobie, że raz w tygodniu workflow pobiera wszystkie nowe kontakty, sprawdza ich tagi i tworzy listę do dalszej komunikacji. API CRM zwraca po 100 rekordów. Proces pobiera pierwszą stronę, czyta wskaźnik kolejnej, pobiera następną i powtarza to aż do końca. Między stronami ogranicza tempo, aby nie wejść w limity szybkości API. Dopiero po zebraniu kompletnej listy uruchamia segmentację. Dzięki temu liczba kontaktów nie zależy od przypadkowego miejsca w paginacji.

Najczęstsze błędy

Najgorszy błąd to założenie, że odpowiedź listy jest pełnym eksportem. Kolejny to zwiększanie limitu strony do maksimum bez sprawdzenia timeoutów i limitów usługi. Nie mieszaj też paginacji z filtrowaniem: filtr może zawęzić dane, ale nadal pozostawić wiele stron. Jeżeli workflow równolegle pobiera strony oparte na kolejności, upewnij się w dokumentacji, że API to wspiera. W przeciwnym razie rekordy mogą się powtórzyć albo zniknąć z wyniku.

Checklist przed uruchomieniem

Sprawdź w oficjalnej dokumentacji: format kolejnej strony, maksymalny rozmiar, stabilne sortowanie, warunek końca i zachowanie przy nowych rekordach. Przetestuj proces na liczbie danych większej niż jedna strona. Zaloguj numer strony lub kursor, liczbę przetworzonych rekordów i błędy. Połącz tę kontrolę z obsługą limitów szybkości API. Dopiero wtedy automatyzacja zbierająca dane do sprzedaży, contentu albo analizy może uczciwie twierdzić, że pracuje na pełnym zbiorze.