Membaca daftar panjang melalui API
Ambil daftar sedikit demi sedikit tanpa melewatkan data. Pahami limit, offset, dan penanda before.
Di halaman ini
API mengembalikan daftar panjang, seperti pelanggan atau pesan, dalam beberapa bagian yang disebut halaman. Mengambil halaman berikutnya disebut paginasi. Dengan cara ini, program tidak perlu mengunduh seluruh riwayat sekaligus.
Ada dua cara melanjutkan pembacaan: melewati sejumlah data yang telah dibaca (offset) atau mengirim penanda posisi terakhir (cursor). Cara yang tersedia untuk setiap alamat API dijelaskan di referensi interaktif.
Cara 1: offset dan X-Total-Count
Parameter limit menentukan jumlah maksimum data dalam satu halaman. Parameter offset menentukan jumlah data yang dilewati. Sebagai contoh, limit=50&offset=100 meminta hingga 50 data setelah 100 data pertama. Tambahkan parameter setelah tanda ? pada alamat:
curl -H "Authorization: Bearer <TOKEN_PRIBADI>" \
"https://domain-anda/api/bots/BOT_ID/users?limit=50&offset=100"
Header respons X-Total-Count menunjukkan jumlah seluruh data. Setelah setiap respons, tambah offset sebesar jumlah data yang benar-benar diterima, sampai mencapai jumlah di X-Total-Count. Isi respons adalah daftar data pada halaman tersebut.
Offset memiliki batas
Nilai offset di atas 100.000 ditolak dengan respons 400 pada semua alamat API yang menerima parameter itu. Jika batas tercapai, persempit hasil dengan filter atau gunakan cursor bila tersedia.
Offset besar juga membuat server bekerja lebih berat karena harus melewati banyak data. Jika daftar lebih dari 100.000 data, Anda dapat:
- membatasi hasil dengan filter, misalnya rentang waktu, saluran, atau status;
- menggunakan cursor jika alamat API mendukungnya, seperti daftar pembayaran dan isi koleksi;
- menggunakan fitur ekspor jika membutuhkan seluruh data sekaligus.
Batas ukuran halaman berbeda
Nilai maksimum limit berbeda untuk setiap alamat API. Ada yang menerima 200, 500, atau 1.000. Periksa nilainya di referensi interaktif.
Jika limit terlalu besar, sebagian alamat API mengirim 400 dan pesan seperti limit must be at most 500, got 5000. Alamat lain memakai nilai bawaan secara diam-diam, biasanya 100, sehingga respons lebih pendek daripada yang diminta.
Karena itu, gunakan jumlah data yang benar-benar diterima untuk menambah offset, bukan nilai limit yang Anda minta. Jika Anda meminta 5.000 tetapi hanya menerima 100, menaikkan offset sebesar 5.000 akan membuat banyak data terlewat tanpa pesan kesalahan.
Jangan mengandalkan halaman kosong sebagai satu-satunya tanda akhir. Perhatikan juga X-Total-Count dan jumlah data yang diterima.
Cara 2: cursor before dan has_more
Daftar yang diurutkan berdasarkan waktu, misalnya pesan percakapan, dapat menggunakan cursor. Permintaan menerima limit dan penanda opsional before, yaitu ID atau penanda data terakhir yang sudah diterima:
curl -H "Authorization: Bearer <TOKEN_PRIBADI>" \
"https://domain-anda/api/bots/BOT_ID/users/USER_ID/dialog?limit=50&before=CURSOR"
Respons berisi satu halaman data dan nilai has_more. Selama nilainya true, ulangi permintaan dengan cursor data terakhir sebagai before. Nilai false berarti Anda sudah mencapai halaman terakhir.
Cara mana yang digunakan?
Cara paginasi ditentukan oleh alamat API. Daftar seperti katalog biasanya memakai offset dan X-Total-Count, sedangkan daftar berdasarkan waktu memakai before dan has_more. Periksa cara yang berlaku pada halaman alamat tersebut di referensi interaktif.
Langkah berikutnya
- Memulai dengan API: permintaan pertama.
- Kesalahan API: kode respons.
- Batas frekuensi dan ukuran: batas permintaan.