Czego szukasz?

Wpisz temat, narzędzie lub problem do rozwiązania.

← Wszystkie artykuły

Paginacja API: jak pobrać wszystkie rekordy zamiast tylko pierwszej strony

Pięć jasnych kartek połączonych czerwoną wstążką na bordowym tle

Import zakończył się bez błędu, ale w bazie jest sto rekordów zamiast kilku tysięcy. Taki wynik często oznacza, że integracja pobrała tylko pierwszą stronę odpowiedzi. Paginacja API dzieli zbiór na części, a poprawny klient musi wiedzieć, jak przejść do następnej i kiedy rzeczywiście zakończyć pracę.

Pokażę różnice między numerem strony, offsetem i kursorem oraz przykład pętli, która wykrywa powtarzający się kursor. Najważniejsza zasada: warunek końca wynika z kontraktu konkretnego API, a nie z przyzwyczajenia programisty.

Co sprawdzić przed napisaniem pętli

Otwórz dokumentację dokładnie tego endpointu, który będzie źródłem danych. Jedna usługa może używać różnych sposobów stronicowania w różnych zasobach. Zapisz nazwy parametrów, rozmiar strony, informację o kolejnej części i ewentualny czas ważności kursora.

Przykładowa odpowiedź może zawierać tablicę items oraz pole next_cursor. Inny serwer zwraca nagłówek Link z relacją next. Jeszcze inny udostępnia has_more i wymaga przekazania identyfikatora ostatniego elementu. Nie zamieniaj tych mechanizmów na jeden własny schemat bez warstwy tłumaczącej.

Kod HTTP 200 potwierdza obsłużenie żądania, nie kompletność całego importu. Zanim przejdziesz do paginacji, powinieneś rozumieć odpowiedź pojedynczego wywołania. W tym pomaga poradnik o REST API. Z kolei formatter JSON ułatwia obejrzenie przykładowej struktury, jeśli nie zawiera ona poufnych danych.

Paginacja API: strona, offset i kursor

Mechanizm Typowe żądanie Najważniejsza uwaga
Numer strony page=2&per_page=100 Sprawdź, od jakiej wartości zaczyna się numeracja
Offset offset=100&limit=100 Przesunięcie dotyczy pozycji w uporządkowanym zbiorze
Kursor cursor=opaque-token Traktuj token jako nieprzezroczystą wartość serwera
Link do następnej części Adres z relacją next Zachowaj parametry i kontroluj dozwolony cel żądania

Przy numerze strony zwykle zwiększasz licznik. Przy offsecie przesuwasz początek pobieranej części zgodnie z dokumentacją. Nie zawsze wolno zwiększać go o liczbę faktycznie otrzymanych elementów: filtracja lub zachowanie serwera mogą zmieniać długość odpowiedzi.

Kursor może reprezentować pozycję, sortowanie, filtr albo stan konkretnej sesji odczytu. Nie dekoduj go po to, żeby samemu zbudować kolejny. Nawet czytelny fragment tokenu nie jest obietnicą stabilnego formatu. W Stripe spotkasz m.in. starting_after i informację has_more; GitHub REST pokazuje wykorzystanie odnośników w nagłówku Link.

Jeśli biblioteka producenta udostępnia iterator wszystkich stron, warto zacząć od niego. Nadal sprawdź limity, zachowanie po błędzie i to, czy iterator pobiera dane leniwie, czy gromadzi cały wynik w pamięci.

Dlaczego przesuwający się zbiór gubi rekordy

Załóżmy, że pobierasz dane posortowane od najnowszych i odczytujesz pierwsze dziesięć pozycji. Przed następnym żądaniem ktoś dodaje dwa nowe rekordy. Pozycje przesuwają się, więc offset=10 może ponownie zwrócić część już pobranych elementów. Usunięcie rekordu może z kolei przesunąć nieodczytany element do wcześniejszej części.

Stabilne sortowanie ogranicza niejednoznaczność kolejności, ale samo nie zamraża danych. Jeżeli kilka rekordów ma tę samą datę, potrzebny jest dodatkowy jednoznaczny klucz, np. identyfikator. To samo zagadnienie pojawia się przy SQL LIMIT i OFFSET: bez odpowiedniego ORDER BY nie należy oczekiwać stabilnego podziału.

Jeżeli API obsługuje spójny snapshot lub token eksportu, wykorzystaj go. Innym rozwiązaniem bywa stała górna granica czasu odczytu, o ile kontrakt API rzeczywiście zapewnia jej oczekiwane znaczenie. Nie obiecuj pełnej spójności tylko dlatego, że endpoint ma parametr cursor.

Usunięcie duplikatów po ID usuwa powtórzenia, lecz nie odzyska pominiętego rekordu. Przy synchronizacji trzeba osobno rozwiązać aktualizacje i usunięcia. Webhooki mogą dostarczać późniejsze zdarzenia, ale wymagają obsługi powtórzeń i sposobu odtworzenia braków.

Przykład pętli z kontrolą postępu

Poniższy kod używa własnego, demonstracyjnego kontraktu. Każda odpowiedź ma dokładnie items i next_cursor, a null oznacza koniec. Rekord posiada tekstowy identyfikator. Pusta strona z niepustym kursorem nie kończy importu.

Zapisz kod jako pagination.py i uruchom python pagination.py. Nie łączy się z internetem i nie wymaga tokenu. Funkcja fetch jest miejscem na adapter konkretnego API.

def collect(fetch, max_pages=100):
    cursor = None
    visited = set()
    records = {}
    for _ in range(max_pages):
        if cursor in visited:
            raise ValueError('Repeated cursor')
        visited.add(cursor)
        page = fetch(cursor)
        if not isinstance(page, dict) or set(page) != {'items', 'next_cursor'}:
            raise ValueError('Unexpected response schema')
        if not isinstance(page['items'], list):
            raise ValueError('items must be a list')
        for item in page['items']:
            if not isinstance(item, dict) or not isinstance(item.get('id'), str):
                raise ValueError('Missing string ID')
            key = item['id']
            if key in records and records[key] != item:
                raise ValueError('Conflicting versions of an ID')
            records[key] = item
        cursor = page['next_cursor']
        if cursor is None:
            return list(records.values())
        if not isinstance(cursor, str) or not cursor:
            raise ValueError('Invalid cursor')
    raise ValueError('Page limit exceeded')

if __name__ == '__main__':
    pages = {
        None: {'items': [{'id': '001'}], 'next_cursor': 'a'},
        'a': {'items': [], 'next_cursor': 'b'},
        'b': {'items': [{'id': '001'}, {'id': '002'}], 'next_cursor': None},
    }
    print(collect(pages.__getitem__))

Wynikiem demonstracji są dwa unikalne rekordy: 001 oraz 002. Pomiędzy pierwszą i ostatnią stroną występuje pusta odpowiedź, a rekord 001 powtarza się. Pętla przechodzi dalej, ponieważ kieruje się kursorem, następnie usuwa identyczne powtórzenie.

Jeżeli ten sam identyfikator pojawi się z inną treścią, przykład zgłasza konflikt. To świadoma decyzja dla eksportu, w którym niespójność wymaga wyjaśnienia. W synchronizacji zmian można wybrać nowszą wersję, ale trzeba mieć wiarygodny numer wersji lub znacznik czasu oraz regułę rozstrzygania.

Kod przechowuje wynik w pamięci. Nadaje się do demonstracji i niewielkiego importu. Przy milionach rekordów zapisuj partie w bazie, a unikalność egzekwuj indeksem. Nie usuwaj jednak ograniczeń liczby stron ani kontroli postępu tylko dlatego, że przenosisz zapis do SQL.

Co faktycznie sprawdzono w testach

Przykład przeszedł siedem lokalnych przypadków: pustą stronę pośrednią z duplikatem, cykl kursora, limit stron, błędny typ items, niepoprawny identyfikator, konflikt wersji oraz pusty zbiór. To test logiki klienta na sztucznych odpowiedziach, nie test konkretnego zewnętrznego dostawcy.

Limit stu stron jest bezpiecznikiem demonstracji. W produkcji ustaw go na podstawie oczekiwanej wielkości zbioru. Przekroczenie limitu powinno zakończyć zadanie błędem, a nie zapisem komunikatu „import zakończony”. Częściowego wyniku nie przedstawiaj jako kompletnego.

Do raportu importu warto dodać: liczbę żądań, pobranych rekordów, unikalnych ID, powtórzeń, odrzuceń i ostatni zapisany punkt postępu. Sama liczba stron nie wystarczy. Jeśli API zwraca total, sprawdź, czy oznacza dokładną wartość, przybliżenie czy stan z momentu pierwszego zapytania.

Adapter HTTP i bezpieczne adresy następnej strony

Adapter powinien ustawić timeout, sprawdzić kod odpowiedzi i zweryfikować strukturę JSON. Dopiero wtedy przekazuje stronę do pętli. Błąd parsowania nie jest pustą listą. Odpowiedź HTML z reverse proxy także nie oznacza końca danych.

Jeżeli dostawca zwraca pełny adres next, nie wysyłaj pod niego bezwarunkowo nagłówka Authorization. Sprawdź dozwolony schemat, host i port. Kontroluj też przekierowania, aby klient nie przeniósł uwierzytelnienia do obcego miejsca. Funkcja składająca URL nie pełni roli polityki bezpieczeństwa. Dokumentacja urllib.parse zwraca uwagę, że bezwzględny drugi argument urljoin może zastąpić host bazowy.

Nagłówek Link ma własną składnię. Proste dzielenie po każdym przecinku może błędnie obsłużyć bardziej złożone wartości. Wybierz sprawdzony parser albo SDK. Zapisany adres kolejnej strony traktuj jako dane techniczne: może zawierać identyfikator sesji, więc nie musi nadawać się do publicznych logów.

Limity, ponawianie i wznowienie importu

Duży eksport potrafi przekroczyć limit żądań mimo poprawnej paginacji. Po odpowiedzi 429 nie zwiększaj kursora. Poczekaj zgodnie z kontraktem serwera i ponów pobranie tej samej części. Zasady Retry-After oraz opóźnień opisuje poradnik o limitach API.

Oddziel ponowienie od zatwierdzenia wyniku. Jeżeli zapisujesz rekordy w bazie, najpierw utrwal partię, a potem jej punkt postępu, najlepiej w jednej transakcji. Zapis kursora przed zapisaniem danych może po awarii spowodować trwałe pominięcie strony.

Zapis danych bez kursora może natomiast doprowadzić do ponownego odczytu tej samej części. To łatwiej obsłużyć przez unikalne ID lub idempotentny zapis. Mechanizm rozwija artykuł o retry bez dublowania efektów.

Kursor może wygasnąć. Dokumentacja powinna wyjaśniać, czy można go przechowywać pomiędzy uruchomieniami. Jeżeli nie, potrzebujesz nowej sesji eksportu lub innego trwałego punktu, np. czasu ostatniej przetworzonej zmiany z kontrolowaną zakładką czasową. Nie zakładaj, że token działa bezterminowo.

Jak przenieść to do automatyzacji

W narzędziu wizualnym zasada jest ta sama: pobierz stronę, sprawdź wynik, zapisz dane, odczytaj następny kursor. Upewnij się, czy node integracji sam pobiera wszystkie strony. Opcja w rodzaju „zwróć wszystkie” może zmieniać liczbę żądań, pamięć i czas wykonania.

Przed podłączeniem harmonogramu uruchom mały import ręcznie. Potem sprawdź zachowanie przy błędzie na środkowej stronie. Jeżeli korzystasz z n8n, zapisuj identyfikator uruchomienia i punkt postępu poza ulotnym przebiegiem, gdy wymagane jest wznowienie po restarcie.

Oddziel zakończenie techniczne od kontroli biznesowej. W zadaniu pobierającym faktury warunkiem sukcesu może być zgodność zakresu dat i liczby dokumentów z raportem źródłowym. Komunikat „workflow wykonany” nie dowodzi, że pobrano wszystkie faktury.

Najczęstsze pytania

Skąd wiadomo, że API zwróciło ostatnią stronę?

Z warunku opisanego przez dostawcę: braku linku next, pustego kursora, has_more=false albo innego sygnału. Mniejsza liczba rekordów nie zawsze oznacza koniec.

Czy kursor jest lepszy od numeru strony?

Często ułatwia przechodzenie przez zmieniający się zbiór, ale jego gwarancje zależą od implementacji. Nie zapewnia automatycznie snapshotu ani możliwości wznowienia po kilku dniach.

Dlaczego po usunięciu duplikatów nadal brakuje danych?

Deduplikacja usuwa nadmiarowe rekordy. Nie wykrywa ani nie odtwarza wszystkich pominięć. Sprawdź stabilność zbioru, sortowanie i sposób przesuwania pozycji między żądaniami.

Czy mogę pobierać kilka stron równolegle?

Tylko jeśli mechanizm API na to pozwala i potrafisz zachować spójność wyniku oraz limity. Przy kolejnym kursorze poznawanym dopiero z odpowiedzi równoległe odgadywanie stron nie jest właściwym rozwiązaniem.

Co zapisać, żeby wznowić przerwany import?

Trwale zapisane dane, parametry eksportu i punkt postępu zgodny z kontraktem API. Sprawdź czas ważności kursora oraz kolejność zatwierdzania. Sam token bez informacji o filtrach może być niewystarczający.

Źródła

Data publikacji: 30.10.2026.

KP
O AUTORZE

Krystian Proć

Tworzę narzędzia do pracy z danymi, systemy backendowe i automatyzacje. Pracuję z SQL, PHP, TypeScriptem i Dockerem; rozwijam m.in. dragon-island.com. AI pomaga mi przyspieszać pracę, a architekturę, weryfikację i decyzje techniczne biorę na siebie. Na Trybie Technicznym dzielę się doświadczeniami z budowania i utrzymywania własnych projektów.

Dyskusja

Dodaj komentarz

Twój adres email nie zostanie opublikowany. Wymagane pola są oznaczone *