Autentikasi, Batasan, dan Struktur Data
Gunakan Authorization: Bearer YOUR_API_KEY atau X-API-Key: YOUR_API_KEY untuk pengambilan terlindungi. Keduanya valid; /v1/status publik tanpa kunci dan gratis. Kunci dan saldo hanya berlaku di redditcommentsapi.com. Sesi panel akun memakai cookie Secure HttpOnly yang terpisah dari autentikasi pengambilan. Kunci ditampilkan sekali sebelum pembayaran; pengguna yang sudah masuk dapat menggantinya setelah konfirmasi kata sandi dan kunci lama langsung tidak berlaku.
Respons API mengembalikan catatan datar, bukan struktur pohon utuh yang disusun di sisi server. Meskipun bidang parent_id dan link_id mungkin hadir, ini tidak menjamin kelengkapan silsilah percakapan. Klien dapat mengelompokkan data secara lokal untuk menyatukan konteks, namun tidak ada jaminan server menyediakan semua cabang percabangan.
Data diurutkan berdasarkan urutan dokumen arsip asli, bukan berdasarkan kronologi waktu atau tingkat relevansi. Batas maksimum pengambilan adalah seratus catatan per permintaan dan seratus halaman per kueri. Penggunaan pengulangan halaman terbatas ini tidak menjamin penelusuran semua catatan atau cakupan total arsip tanpa jeda.
Rute, Filter, dan Parametrisasi Data
GET /v1/search mendukung q, subreddit, author, kind, from, to, min_score, limit, dan page. kind menggunakan post atau comment. Tanggal memakai YYYY-MM-DD dalam UTC, dengan to inklusif. GET /v1/comments dan GET /v1/posts tidak memakai id pada daftar. GET /v1/item memerlukan id untuk satu catatan yang sudah diketahui. Bidang hubungan bukan jalur otomatis untuk menelusuri semua balasan dari suatu postingan.
Filter hanya mencakup variabel teks, subreddit, penulis, rentang tanggal ISO, dan skor minimum. Bidang id hanya wajib untuk rute item spesifik. Rute pos dan komentar tidak memerlukan id karena mereka mengambil data berbasis daftar. Parameter min_score bertindak sebagai filter, bukan pengurut, sehingga hasil tidak diurutkan berdasarkan skor tersebut.
GET /v1/subreddits memakai prefix dan limit untuk penemuan nama komunitas; hitungannya tidak dijamin eksak secara global. parent_id dan link_id dapat dipakai secara lokal jika tersedia, bukan sebagai filter kueri. Total eq adalah hitungan eksak, gte batas bawah, unknown tidak diketahui dan total dapat null. Ini total catatan cocok, bukan jumlah halaman, dan bukan bukti cakupan lengkap atau keadaan pemrosesan seluruh arsip.
Penanganan Error dan Kode HTTP
HTTP 400 menunjukkan permintaan tidak valid, 401 kunci hilang atau tidak valid, 402 saldo kurang, dan 429 batas laju. Permintaan tidak valid tidak mendebit kredit; kegagalan sumber data mengembalikan cadangan. Putusnya koneksi klien dapat terjadi setelah keberhasilan yang ditagih; pengulangan berhasil memakai kredit baru. Hasil kosong yang berhasil juga satu kredit. Perbaiki parameter atau kunci, hentikan atau isi saldo saat 402, dan tunggu saat 429.
Contoh /v1/comments?subreddit=learnprogramming&limit=3 meminta paling banyak tiga komentar, bukan seluruh utas atau tiga catatan yang saling berhubungan. Simpan respons sebelum memperbarui titik lanjut lokal. Periksa jenis dan keberadaan bidang hubungan; tandai induk yang hilang, duplikasi pengenal, atau hubungan yang merujuk diri sendiri. Pemeriksaan lokal ini adalah saran pemrosesan klien, bukan fitur server yang menjamin konteks lengkap.
/v1/status hanya memberikan penjelasan statis dan respons HTTP; tidak menguji pencarian, kunci, kueri, atau ketersediaan catatan. Simpan parameter dan respons nyata untuk meninjau keputusan analisis. Pembayaran terpisah dari status: masuk, buat faktur, kirim jumlah tepat sesuai token, jaringan dan penerima saat ini, lalu ajukan hash transaksi. Kredit memerlukan verifikasi server atas transfer terkonfirmasi, tanpa jaminan waktu penyelesaian. Pengembalian cadangan pengambilan bukan janji pengembalian salah transfer.
