Cursor Pagination pada REST API: Cara Menangani Data Besar dengan Efisien

Ketika aplikasi menampilkan ribuan transaksi, artikel, notifikasi, atau catatan aktivitas, mengirim semua data sekaligus bukan pilihan yang baik. Respons menjadi besar, waktu tunggu meningkat, dan database harus bekerja lebih keras. Pagination membagi hasil menjadi beberapa bagian. Untuk data yang terus berubah, salah satu pendekatan yang layak dipertimbangkan adalah cursor pagination.

Berbeda dari pagination berbasis nomor halaman, cursor pagination menggunakan penanda posisi yang dikirim kembali oleh klien saat meminta data berikutnya. Pola ini umum dipakai pada API yang menyajikan linimasa, katalog, log, atau hasil pencarian dalam jumlah besar.

Apa Itu Cursor Pagination?

Cursor pagination mengambil sejumlah item dan mengembalikan token yang menunjukkan dari mana permintaan selanjutnya harus dilanjutkan. Token itu bisa disebut cursor, next_cursor, atau page_token. Klien tidak perlu menghitung nomor halaman; cukup meneruskan token yang diberikan server.

Misalnya, endpoint mengembalikan 20 transaksi dan sebuah cursor lanjutan. Aplikasi mengirim cursor tersebut pada permintaan berikutnya, lalu server memberikan kumpulan setelah posisi itu. Cursor idealnya diperlakukan sebagai token buram: klien menyimpannya dan mengirimkannya kembali tanpa mencoba mengubah isi internalnya.

Cursor Pagination vs. Offset Pagination

Offset pagination memakai parameter seperti limit=20&offset=1000. Cara ini mudah dipahami dan cocok untuk daftar yang kecil atau kebutuhan melompat ke halaman tertentu. Namun, offset yang sangat besar dapat memaksa database melewati banyak baris sebelum menghasilkan data. Perubahan data saat pengguna berpindah halaman juga bisa menyebabkan item terlewat atau tampil dua kali.

Cursor pagination biasanya lebih cocok untuk pengambilan data berurutan dan berkelanjutan. Karena permintaan dimulai dari nilai penanda, kinerjanya dapat lebih stabil pada dataset besar—dengan catatan indeks dan kueri dirancang dengan benar. Kekurangannya, melompat langsung ke halaman ke-50 tidak sesederhana pagination berbasis offset, dan implementasinya membutuhkan aturan pengurutan yang jelas.

Merancang Cursor yang Stabil

Fondasi cursor yang baik adalah urutan yang deterministik. Jangan mengurutkan data hanya berdasarkan waktu jika beberapa catatan dapat memiliki timestamp yang sama. Tambahkan kolom unik sebagai pemecah seri, misalnya ID. Dengan begitu, urutan gabungan seperti created_at lalu id tetap jelas.

Contoh konsepnya: server mengurutkan transaksi berdasarkan waktu terbaru, kemudian ID menurun. Cursor menyimpan nilai waktu dan ID dari item terakhir yang ditampilkan. Permintaan berikutnya mencari item yang posisinya berada setelah pasangan nilai tersebut dalam urutan yang sama. Detail operator pembanding bergantung pada arah pengurutan dan mesin database yang digunakan.

Cursor tidak harus memuat data sensitif. Jika token menyandikan nilai internal, pertimbangkan format buram atau penandatanganan agar klien tidak bisa mengubah posisi secara sembarangan. Penandatanganan membantu mendeteksi manipulasi, tetapi bukan pengganti otorisasi. Setiap permintaan tetap harus memeriksa identitas pengguna dan batas akses terhadap data.

Contoh Pola API

Respons API dapat menyertakan daftar data dan cursor untuk permintaan berikutnya. Bentuk persisnya bergantung pada kontrak API, tetapi pola umumnya seperti berikut:

{
  "data": [
    { "id": 501, "name": "Contoh item" }
  ],
  "next_cursor": "token-dari-server",
  "has_more": true
}

Klien lalu meminta endpoint yang sama dengan parameter cursor, misalnya ?limit=20&cursor=token-dari-server. Bila tidak ada data lanjutan, server dapat mengirim next_cursor bernilai null atau has_more bernilai false. Pilih satu kontrak yang konsisten dan dokumentasikan cara mengakhiri pemuatan.

Praktik Implementasi yang Perlu Diperhatikan

• Tetapkan batas maksimum. Batasi nilai limit agar klien tidak meminta ribuan item dalam satu respons.
• Gunakan indeks yang sesuai. Kolom untuk filter dan pengurutan cursor perlu dievaluasi dengan rencana kueri database, bukan hanya ditebak.
• Validasi token. Tangani cursor yang rusak, kedaluwarsa, atau tidak sesuai versi API dengan respons kesalahan yang jelas.
• Jaga konsistensi filter. Cursor sebaiknya digunakan bersama filter dan urutan yang sama dengan permintaan awal. Jika filter berubah, mulai kembali dari awal.
• Rancang perilaku saat data berubah. Cursor membantu mengurangi masalah pergeseran halaman, tetapi tidak otomatis membuat snapshot konsisten. Tentukan apakah hasil boleh mencerminkan perubahan terbaru atau perlu mekanisme snapshot.
• Hindari kebocoran informasi. Jangan menganggap cursor sebagai izin akses. Periksa hak pengguna untuk setiap permintaan dan jangan menyimpan rahasia dalam token yang mudah dibaca.
• Uji batas kasus. Periksa dataset kosong, item dengan waktu sama, item baru yang masuk saat proses berlangsung, penghapusan data, serta permintaan berulang.

Kapan Sebaiknya Digunakan?

Cursor pagination tepat untuk linimasa, aktivitas akun, log sistem, pesan, katalog besar, dan API yang terutama digunakan untuk mengambil data secara berurutan. Offset pagination tetap masuk akal untuk tabel administratif sederhana yang membutuhkan navigasi halaman langsung dan jumlah data terbatas.

Sebelum memilih, ukur pola akses aplikasi, ukuran dataset, kebutuhan pengguna, dan kemampuan database. Implementasi cursor yang kompleks tidak selalu diperlukan untuk daftar kecil. Sebaliknya, menunggu sampai performa memburuk dapat membuat perubahan kontrak API lebih sulit karena klien telanjur bergantung pada format lama.

Kesimpulan

Cursor pagination merupakan strategi efektif untuk mengambil data besar secara bertahap, terutama ketika urutan data perlu tetap stabil saat dataset berubah. Kunci keberhasilannya bukan sekadar menambahkan parameter cursor, melainkan menentukan urutan yang konsisten, merancang indeks, memvalidasi token, menjaga otorisasi, dan mendokumentasikan perilaku API. Mulailah dari kebutuhan nyata, uji dengan data yang mendekati kondisi produksi, lalu pantau latensi serta beban database untuk memastikan pendekatan tersebut memang memberi manfaat.