Autentikasi dan ruang lingkup rute
Permintaan pengambilan menggunakan metode GET dan salah satu header Authorization: Bearer <key> atau X-API-Key: <key>. Keduanya didukung. Kunci berlaku untuk akun redditlistening.com, bukan semua merek dalam jaringan. Cookie sesi Secure HttpOnly dipakai untuk panel akun dan berbeda dari autentikasi pengambilan. Jangan menempelkan cookie akun atau kata sandi sebagai pengganti kunci pada contoh kueri.
/v1/search, /v1/posts, dan /v1/comments menerima q, subreddit, author, kind, from, to, min_score, limit, serta page. kind memakai nilai post atau comment. Rute posts dan comments membatasi jenis rekaman dan tidak memerlukan id. /v1/item?id=... digunakan untuk mencari satu rekaman berdasarkan id. Parameter parent_id dan link_id bukan filter yang tersedia untuk pencarian.
/v1/subreddits hanya menerima prefix dan limit. Rute ini bukan pencarian isi percakapan dengan filter tanggal atau pagination page; hitungannya tidak dijamin tepat secara global. /v1/status bersifat publik dan tidak menggunakan kredit. Responsnya mengungkapkan ruang lingkup layanan secara statis dan menunjukkan server HTTP merespons, bukan memeriksa mesin pencarian, keberadaan rekaman, maupun kelengkapan arsip.
Tanggal dan bentuk data
Gunakan from dan to dalam format YYYY-MM-DD dengan hari UTC. Filter diterapkan pada created_utc. Batas to mencakup seluruh hari yang ditentukan, bukan hanya tengah malam; jika Anda mengisi tanggal UTC hari ini, seluruh hari ini termasuk dalam batas tersebut. Waktu pembuatan rekaman tidak otomatis menunjukkan kapan produk dibeli, rusak, atau digunakan oleh penulis.
Data yang dikembalikan melalui API berada dalam bentuk rekaman datar, bukan pohon utas yang telah dirakit di sisi server. Meskipun field parent_id dan link_id mungkin hadir dalam rekaman yang dikembalikan, klien dapat mengelompokkan data secara lokal jika diperlukan. Namun, pengelompokan itu tidak menjamin percakapan lengkap atau seluruh hubungan dengan rekaman induk karena arsip mungkin tidak mencakup semua data percakapan terkait.
limit berada dalam rentang 1–100 dan page dalam rentang 1–100 untuk kueri konten. Urutannya _doc, bukan kronologis, relevansi, atau skor. min_score hanya ambang penyaringan. Total dengan relasi eq berarti tepat, gte berarti batas bawah, dan unknown berarti tidak ada total yang dapat diandalkan; nilainya mungkin null. Total maupun pembagian kueri tidak membuktikan cakupan lengkap atau sampel yang mewakili konsumen.
Kesalahan dan catatan pengambilan
HTTP 400 berarti permintaan tidak valid, 401 berarti kunci hilang atau tidak valid, 402 berarti kredit tidak cukup, dan 429 berarti batas frekuensi permintaan. Periksa parameter ketika mendapat 400, kunci ketika 401, dan saldo domain ini ketika 402. Tunggu sebelum mencoba kembali setelah 429. Jangan menambah parameter tak terdokumentasi untuk memaksa urutan atau memperoleh percakapan lengkap.
Permintaan tidak valid tidak memotong kredit; kegagalan sumber mengembalikan kredit yang dicadangkan. Pengambilan berhasil tetap memakai satu kredit walaupun kosong. Hilangnya respons pada klien tidak membuktikan server gagal: keberhasilan yang sudah selesai dapat ditagih, dan percobaan ulang yang berhasil memakai kredit lagi. Pisahkan kegagalan menerima respons dari hasil kosong yang benar-benar diterima dalam log aplikasi.
Untuk riset ransel, simpan kondisi kueri backpack, komunitas BuyItForLife, tanggal pengambilan, dan keputusan mengikutkan rekaman. Deduplicasi lokal dapat mengurangi penghitungan berulang pada data yang sudah diperoleh, tetapi tidak memulihkan data yang tidak tersedia. Tentukan unit analisis sebelum menjumlahkan: satu penulis bisa menghasilkan beberapa komentar, sementara satu komentar bisa membahas lebih dari satu produk.
