Paginasi

Daftar memakai paginasi berbasis kursor: kamu meminta satu halaman, dan id item terakhir yang kamu punya menjadi kursor untuk halaman berikutnya. Daftar terbaru dahulu.

Objek paginasi

GET /v1/payments, GET /v1/payment-links, GET /v1/invoices, GET /v1/webhook-deliveries, dan GET /v1/events mengembalikan satu halaman di data, dan menunjukkan kelanjutan daftarnya di meta.pagination:

{
  "data": [
    { "id": "pay_01k7q3m8x2v5t9n4b6c1d0e7fa", "status": "paid", "amount": 1000000, "currency": "IDR" },
    { "id": "pay_01k7q3m8x2v5t9n4b6c1d0e7f9", "status": "pending", "amount": 500000, "currency": "IDR" }
  ],
  "meta": {
    "request_id": "req_Hy3k9QzT2LmN8vXa",
    "pagination": {
      "per_page": 20,
      "has_more": true,
      "next": "https://api.baiyar.com/v1/payments?limit=20&starting_after=pay_01k7q3m8x2v5t9n4b6c1d0e7f9"
    }
  }
}

Field	Tipe	Artinya
data	array	Item di halaman ini, terbaru dahulu
meta.pagination.per_page	integer	Ukuran halaman yang dipakai
meta.pagination.has_more	boolean	Apakah masih ada halaman berikutnya.
meta.pagination.next	string atau null	Alamat halaman berikutnya, dengan filter request ini, atau null kalau tidak ada

Tidak ada jumlah total: minta halaman sampai has_more bernilai false.

Operasi daftar

Ukuran halaman

Pakai limit untuk mengatur ukuran halaman. Bawaannya 20, dari 1 sampai 100.

Pindah halaman

Ambil meta.pagination.next apa adanya: filter dan kursor sudah ada di dalamnya. Atau kirim sendiri starting_after, yaitu id item terakhir di halaman yang kamu punya:

GET /v1/payments?limit=50&starting_after=pay_01k7q3m8x2v5t9n4b6c1d0e7f9

Pertahankan filter yang sama selama berpindah halaman. Berhenti saat has_more bernilai false.

Tanpa hasil

Daftar yang kosong dijawab 200 dengan "data": [] dan "has_more": false.

Baca semua halaman

Node.js

const headers = { Authorization: `Bearer ${process.env.BAIYAR_KEY}` };

async function* allPayments() {
  let url = "https://api.baiyar.com/v1/payments?limit=100";
  while (url) {
    const { data, meta } = await (await fetch(url, { headers })).json();
    yield* data;
    // `next` membawa filter request ini dan kursor item terakhirnya
    url = meta.pagination.has_more ? meta.pagination.next : null;
  }
}

for await (const payment of allPayments()) console.log(payment.id, payment.status);

Python

import os
import requests

headers = {"Authorization": f"Bearer {os.environ['BAIYAR_KEY']}"}


def all_payments():
    url = "https://api.baiyar.com/v1/payments?limit=100"
    while url:
        body = requests.get(url, headers=headers).json()
        yield from body["data"]
        # `next` membawa filter request ini dan kursor item terakhirnya
        pagination = body["meta"]["pagination"]
        url = pagination["next"] if pagination["has_more"] else None


for payment in all_payments():
    print(payment["id"], payment["status"])

Mutasi saldo

GET /v1/balance/movements memakai kursor lain, karena entri-nya diurutkan menurut angka, bukan id. meta.pagination.next sudah memuat kursornya, sebagai before; kamu juga bisa mengirim before sendiri. meta.account menunjukkan saldo mana yang dimaksud mutasi itu:

{
  "data": [ … ],
  "meta": {
    "request_id": "req_Hy3k9QzT2LmN8vXa",
    "account": "available",
    "pagination": {
      "per_page": 20,
      "has_more": true,
      "next": "https://api.baiyar.com/v1/balance/movements?account=available&before=184"
    }
  }
}

next bernilai null kalau sudah tidak ada lagi.

Tanpa halaman

GET /v1/event-types dan GET /v1/webhook-endpoints mengembalikan semuanya di data: jumlahnya sedikit (sampai lima endpoint per cakupan). Keduanya tidak punya pagination.

Praktik terbaik

• Baca sebuah daftar sekali dan simpan yang sudah dibaca, jangan membacanya berulang-ulang.
• Pakai limit terbesar yang cocok untuk mengurangi jumlah request. Lihat Rate limit.
• Item baru bisa muncul saat kamu berpindah halaman. Karena kursornya id, kamu tidak melihat item dua kali dan tidak melewatkan satu pun.
• Jangan mengubah filter di antara dua halaman dari bacaan yang sama.

Halaman terkait

• Respons sukses
• Filter daftar
• Daftar pembayaran