Paginacja

Endpointy listujące w API zwracają dane stronicami. Na platformie historycznie wykształciły się dwa schematy paginacji; konkretny schemat jest opisany przy endpoincie w interaktywnej dokumentacji.

Schemat 1 — przesunięcie i X-Total-Count

Klasyczna paginacja oparta na przesunięciu. Żądanie przyjmuje parametry query limit (rozmiar strony) i offset (ile rekordów pominąć):

curl -H "Authorization: Bearer mbp_TWÓJ_TOKEN" "https://twoja-domena/api/bots/BOT_ID/subscribers?limit=50&offset=100"

Łączna liczba rekordów jest zwracana w nagłówku odpowiedzi X-Total-Count. Na jego podstawie wylicza się liczbę stron: stronicuj, zwiększając offset o limit, dopóki offset jest mniejszy niż wartość X-Total-Count. Treść odpowiedzi to tablica elementów bieżącej strony.

Schemat 2 — kursor before i has_more

Paginacja kursorowa dla strumieni posortowanych chronologicznie (np. wiadomości dialogu). Żądanie przyjmuje limit i opcjonalny kursor before — identyfikator lub znacznik ostatnio pobranego elementu:

curl -H "Authorization: Bearer mbp_TWÓJ_TOKEN" "https://twoja-domena/api/bots/BOT_ID/users/USER_ID/dialog?limit=50&before=CURSOR"

Odpowiedź zawiera stronę elementów oraz flagę has_more. Dopóki has_more wynosi true, powtarzaj żądanie, przekazując w before kursor ostatnio pobranego elementu. Gdy has_more stanie się false — to ostatnia strona.

Który schemat wybrać

Nie wybierasz schematu — wyznacza go endpoint. Listy-słowniki zazwyczaj używają przesunięcia i X-Total-Count; strumienie chronologiczne — kursora before i has_more. Zawsze sprawdzaj stronę endpointu w dokumentacji.

Co dalej