Autentikasi dan Struktur Respons Data
Pengambilan terlindungi menerima Authorization: Bearer YOUR_API_KEY atau X-API-Key: YOUR_API_KEY; keduanya valid. /v1/status bersifat publik tanpa kunci dan tidak ditagih. HTTP 401 berarti kunci tidak ada atau tidak valid, bukan sesi panel akun yang kedaluwarsa. Kunci dan saldo hanya berlaku di redditpostsapi.com. Jangan menaruh kunci asli dalam URL, kode browser publik, atau berkas contoh untuk dibagikan kepada analis lain.
Respons yang dikembalikan oleh server adalah rekaman datar yang sederhana dan langsung. Struktur ini tidak menyusun pohon utas percakapan secara otomatis di sisi server, sehingga klien memiliki kebebasan untuk mengelompokkan data secara lokal jika diperlukan. Jika bidang parent_id dan link_id tersedia, keduanya memungkinkan pemetaan hubungan dasar, namun tidak menjamin kelengkapan riwayat percakapan atau silsilah postingan secara penuh.
Pengelompokan lokal bersifat opsional dan tidak menjamin kelengkapan percakapan. Periksa bidang yang benar-benar tersedia dan dokumentasikan teks, waktu, atau pengenal yang hilang. Tidak ada filter kueri parent_id atau link_id. Untuk memeriksa satu catatan yang sudah diketahui, gunakan GET /v1/item dengan id. GET /v1/posts dan GET /v1/comments tidak memakai id sebagai parameter daftar. Pemilihan rute tidak mengubah sifat arsip menjadi data langsung.
Parameter Kueri dan Semantik Filter
Filter pencarian adalah q, subreddit, author, kind, from, to, min_score, limit, dan page. Nilai kind adalah post atau comment. from dan to memakai YYYY-MM-DD dalam UTC dengan to inklusif. Filter tanggal bersifat opsional dan bekerja pada batas hari, bukan jam atau menit. GET /v1/subreddits memakai prefix dan limit untuk penemuan nama komunitas; hitungannya tidak dijamin eksak secara global.
Filter min_score bertindak semata-mata sebagai penyaring ambang batas, bukan sebagai mekanisme pengurutan peringkat hasil. Pengurutan rekaman dalam arsip mengikuti urutan dokumen internal _doc, yang tidak selalu mencerminkan urutan kronologis, relevansi, maupun skor. Pengguna tidak boleh mengasumsikan bahwa hasil yang ditampilkan sudah terurut berdasarkan popularitas atau tanggal terbaru secara otomatis.
limit dan page bernilai 1–100: paling banyak 100 catatan per permintaan dan 100 halaman per kueri. Relasi total eq berarti eksak, gte batas bawah, unknown tidak diketahui dan total dapat null. Ini adalah total catatan yang cocok, bukan jumlah halaman. Pengulangan sampai batas tidak menjamin pengambilan seluruh hasil; total eksak pun tidak membuktikan semua catatan telah diterima dan disimpan oleh klien.
Penanganan Kesalahan dan Status Sistem
HTTP 400 menunjukkan permintaan tidak valid, 401 kunci hilang atau tidak valid, 402 saldo tidak mencukupi, dan 429 batas laju. Perbaiki parameter atau kunci sebelum mengulang dan tunggu jika dibatasi. Permintaan tidak valid tidak mendebit kredit; kegagalan sumber data mengembalikan cadangan. Keberhasilan yang tidak diterima klien tetap dapat ditagih, dan pengulangan berhasil memakai kredit tambahan. Hasil kosong yang berhasil tetap satu kredit.
/v1/status hanya memberikan penjelasan statis dan menunjukkan bahwa server HTTP merespons. Ini tidak memeriksa kesehatan pencarian, keberadaan catatan, atau cakupan arsip. Simpan respons pengambilan yang benar-benar diterima sebelum melanjutkan penanda kemajuan lokal. Contoh kecil /v1/posts?subreddit=photography&min_score=10&limit=3 berguna untuk memeriksa bentuk catatan; tidak membuktikan keberadaan diskusi peralatan atau memberikan hasil analisis yang sudah dihitung server.
Pengguna yang sudah masuk dapat mengganti kunci setelah konfirmasi kata sandi dan langsung membatalkan kunci lama. Kunci ditampilkan sekali saat pendaftaran sebelum pembayaran, tidak dikirim melalui email, dan tidak ada pengaturan ulang kata sandi. Untuk membayar, buat faktur setelah masuk, gunakan token, jaringan, penerima serta jumlah tepat yang tertera, lalu kirim hash transaksi untuk verifikasi. Tidak ada jaminan waktu penyelesaian pembayaran.
