Haurin
Masuk

Dokumentasi API internal

Handler internal yang dipakai web Haurin sendiri. Daftar ini untuk pengembang yang mengerjakan web atau bot, bukan untuk pemakaian luar. Handler internal boleh berubah tanpa pemberitahuan. Untuk pemakaian luar, pakai API publik v1 dan spesifikasinya di openapi.json. Jumlah di halaman ini 20 handler, bukan 18 seperti yang tertulis di rencana awal, karena dua handler ditambahkan sesudah rencana itu ditulis: klaim setup key dan audit log admin.

Yang berlaku untuk semua handler

  • Semua error memakai amplop yang sama: { ok: false, error, code } dengan pesan berbahasa Indonesia dan kode mesin stabil. Daftar kode ada di openapi.json.
  • Semua response membawa header x-request-id.
  • 429 selalu sama di semua route: amplop RATE_LIMITED + header Retry-After: 60 + X-RateLimit-Remaining.
  • 503 dibedakan: MIGRATION_MISSING bila migrasi database belum diterapkan, UPSTREAM_UNAVAILABLE bila database tidak terjangkau, WRITE_FAILED bila tulis terverifikasi gagal.
  • Body request POST dibatasi 256 KiB. Lebih dari itu dijawab 413 BODY_TOO_LARGE sebelum body dibaca.
  • Rate limit tulis dan destruktif memakai bucket global (RPC check_rate_limit) dua fase: fase 1 per IP sebelum auth, fase 2 per user sesudah sesi diketahui. Bila RPC tidak bisa dipakai, penegakan jatuh ke bucket in-memory per instance dan degradasi itu tercatat di log. Rate limit baca memakai bucket per instance.
  • Bentuk sukses TIDAK seragam. Yang memakai amplop { ok: true, data }: marketplace, favorites, ratings, setups claim, dan audit log admin. Pengecualian bentuk sukses ada delapan kelompok, tercantum di bawah. Ini sengaja, karena konsumen di aplikasi membaca field langsung.

Delapan pengecualian bentuk sukses

Delapan handler di bawah ini suksesnya mentah, bukan amplop. Errornya tetap memakai amplop. Jangan menulis kode yang mengasumsikan semua sukses berbentuk { ok: true, data }.

  • POST /api/customize → { key, command, mode, snapshot, publish_status }
  • GET /api/my-setup-status → { loggedIn, found, phase, completedAt, error }
  • GET /api/bot-status → { state, last_seen }
  • GET /api/health → { status, version, public_url, templates, total_channels } (tanpa field ok, sengaja, supaya monitor eksternal tetap jalan)
  • GET /api/templates, GET /api/templates/[id], GET /api/setup/[key] → template mentah atau { templates }
  • GET /api/notifications → { ok: true, notifications }
  • DELETE /api/account → { ok: true, deleted, unavailable }
  • POST /api/feedback, POST /api/notifications, DELETE /api/setups/[key] → { ok: true }

Tanpa login

GET/api/health

Auth
Tidak ada
Rate limit
60/menit per IP (per instance)
Sukses
{ status, version, public_url, templates, total_channels }
Error
429
Dipakai monitor eksternal dan halaman /status. version diambil dari package.json. Bentuk sukses sengaja tanpa field ok.

GET/api/templates

Auth
Tidak ada
Rate limit
60/menit per IP (per instance)
Sukses
{ templates }
Error
429
Dipakai galeri dan editor. Mengembalikan snapshot penuh tiap template, berbeda dengan GET /api/v1/templates yang hanya ringkasan.

GET/api/templates/[id]

Auth
Tidak ada
Rate limit
60/menit per IP (per instance)
Sukses
Template apa adanya
Error
404 TEMPLATE_NOT_FOUND, 429
Satu template penuh berdasarkan ID.

GET/api/setup/[key]

Auth
Tidak ada
Rate limit
60/menit per IP (per instance)
Sukses
Template apa adanya
Error
400 INVALID_SETUP_KEY, 404 SETUP_NOT_FOUND, 429
Dipakai dialog dan pratinjau. Key 12 atau 32 hex dibaca lewat RPC get_setup_by_key; slug dibaca sebagai ID template resmi tanpa RPC.

GET/api/marketplace

Auth
Tidak ada
Rate limit
60/menit per IP (per instance)
Sukses
{ ok: true, data: { usage, ratings } }
Error
429
Agregat publik untuk galeri: pemakaian nyata + rating per template. Rating dihitung lewat RPC agregat get_ratings_summary dan di-cache 60 detik, jadi ulasan baru bisa telat tampil sampai 60 detik.

GET/api/ratings?template=<id>

Auth
Tidak ada (login memberi myRating)
Rate limit
60/menit per IP (per instance)
Sukses
{ ok: true, data: { avg, count, reviews, myRating } }
Error
400 INVALID_REQUEST, 429
Rata-rata dihitung di database atas seluruh baris; daftar ulasan dibatasi 50 terbaru. Reviewer tampil sebagai pseudonim stabil u_ + 12 hex sha256(user_id), bukan user_id mentah.

GET/api/bot-status

Auth
Tidak ada
Rate limit
60/menit per IP (per instance)
Sukses
{ state, last_seen }
Error
429
Dipakai banner status di dialog dan panel key. Membaca bot_heartbeat yang sama dengan /status. state mengikuti laporan bot sendiri yang belum terverifikasi.

POST/api/customize

Auth
Boleh anonim; publish wajib login
Rate limit
10/10 menit per IP (global) + 10/10 menit per user bila login (global)
Sukses
{ key, command, mode, snapshot, publish_status }
Error
400 INVALID_JSON / INVALID_MODE / INVALID_SNAPSHOT + errors, 401 UNAUTHORIZED, 429, 503
Dipakai ruang rakit. Publish tanpa login dijawab 401 dengan pesan login diperlukan untuk publish. Di produksi, gagal insert dijawab 503 WRITE_FAILED, bukan sukses palsu. Notifikasi hanya membawa 8 karakter akhir key.

POST/api/feedback

Auth
Boleh anonim; bila login, user_id dicatat
Rate limit
10/jam per IP (global) + 10/jam per user bila login (global)
Sukses
{ ok: true }
Error
400 INVALID_REQUEST, 429, 503 MIGRATION_MISSING / WRITE_FAILED
Form masukan di /docs dan footer. Pesan 10 sampai 1000 karakter.

Butuh login

GET/api/my-setup-status

Auth
Sesi login (tanpa login: { loggedIn: false })
Rate limit
30/menit per IP (global)
Sukses
{ loggedIn, found, phase, completedAt, error }
Error
429
Dipakai tombol Cek hasil setup saya. Tanpa akun, web tidak tahu server mana yang dimaksud, jadi hasil hanya tampil di Discord.

GET/api/favorites

Auth
Sesi login
Rate limit
60/menit per IP (per instance)
Sukses
{ ok: true, data: string[] }
Error
401 UNAUTHORIZED, 429, 503
Daftar ID template favorit milik user.

POST/api/favorites

Auth
Sesi login
Rate limit
30/menit per IP (global) + 30/menit per user (global)
Sukses
{ ok: true, data: string[] }
Error
400 INVALID_REQUEST, 401, 404 TEMPLATE_NOT_FOUND, 429, 503
Simpan favorit. Duplikat diabaikan (upsert). Pemilik template custom diberi tahu, kecuali actor adalah owner.

DELETE/api/favorites?template=<id>

Auth
Sesi login
Rate limit
30/menit per IP (global) + 30/menit per user (global)
Sukses
{ ok: true, data: string[] }
Error
400 INVALID_REQUEST, 401, 429, 503
Hapus favorit milik user.

POST/api/ratings

Auth
Sesi login
Rate limit
20/menit per IP (global) + 20/menit per user (global)
Sukses
{ ok: true, data: { avg, count } }
Error
400 INVALID_REQUEST, 401, 404 TEMPLATE_NOT_FOUND, 429, 503
Satu ulasan per user per template (upsert). Rating bilangan bulat 1 sampai 5, ulasan maksimal 500 karakter.

GET/api/notifications

Auth
Sesi login
Rate limit
60/menit per IP (per instance)
Sukses
{ ok: true, notifications }
Error
401 UNAUTHORIZED, 429
20 notifikasi terbaru dulu. Bila tabel belum ada, menjawab daftar kosong, bukan error. Isi notifikasi tidak pernah memuat setup key utuh, hanya 8 karakter akhirnya.

POST/api/notifications

Auth
Sesi login
Rate limit
30/menit per IP (global) + 30/menit per user (global)
Sukses
{ ok: true }
Error
400 INVALID_REQUEST, 401, 404 NOTIFICATION_NOT_FOUND, 429, 503
Body { id } menandai satu notifikasi, { markAll: true } menandai semua milik user.

DELETE/api/setups/[key]

Auth
Sesi login
Rate limit
30/menit per IP (global) + 30/menit per user (global)
Sukses
{ ok: true }
Error
401 UNAUTHORIZED, 404 SETUP_NOT_FOUND, 429, 503 WRITE_FAILED
Cabut setup key milik sendiri. Key orang lain menjawab 404 yang sama seperti key yang tidak ada.

POST/api/setups/claim

Auth
Sesi login
Rate limit
10/jam per IP (global) + 10/jam per user (global)
Sukses
{ ok: true, data: { claimed } }
Error
400 INVALID_SETUP_KEY, 401, 429, 503 MIGRATION_MISSING
Klaim setup key yatim (dibuat tanpa login) menjadi milik user, lewat RPC claim_setup. RPC belum diterapkan dijawab 503 MIGRATION_MISSING, bukan klaim palsu. Keberadaan RPC dideteksi lewat dokumen OpenAPI PostgREST dan di-cache 60 detik. Klaim yang gagal karena key tidak bisa diklaim menjawab claimed false dengan pesan generik, supaya tidak membocorkan keberadaan key milik orang lain.

DELETE/api/account

Auth
Sesi login + body { confirm: 'HAPUS' } persis
Rate limit
5/jam per IP (global) + 5/jam per user (global)
Sukses
{ ok: true, deleted, unavailable }
Error
400 INVALID_REQUEST, 401, 429, 503 WRITE_FAILED
Hapus semua data milik user: setups, favorites, template_ratings, api_keys, notifications, profiles. Baris auth.users TIDAK dihapus (butuh service key yang tidak dimiliki web). Penghapusan atomik lewat RPC delete_account_data bila RPC sudah live; bila belum, hapus per tabel + degradasi tercatat.

Admin

GET/api/admin/audit-log?limit=50

Auth
Sesi login + admin (env ADMIN_EMAIL atau tabel admins)
Rate limit
60/menit per IP (per instance)
Sukses
{ ok: true, data: { entries, count } }
Error
401 UNAUTHORIZED, 403 FORBIDDEN, 429, 503
Baca audit log, terbaru dulu, maksimal 200 baris. Dua lapis otorisasi, keduanya fail-closed: web memeriksa admin, dan RPC get_audit_log memeriksa admin di dalam fungsi. RPC null dijawab 503 yang dibedakan, bukan 0 baris palsu.

Catatan kejujuran

  • Hasil pemeriksaan "apakah RPC verify_api_key ada" di-cache 60 detik. Sesudah migrasi diterapkan, klasifikasi 401 vs 503 yang baru benar paling lambat 60 detik kemudian. Hasil yang tidak diketahui (gagal jaringan, timeout, 5xx) tidak di-cache.
  • Agregat rating marketplace di-cache 60 detik. Ulasan baru bisa telat tampil sampai 60 detik, sama seperti angka pemakaian.
  • Status bot di /api/bot-status dan /status berasal dari laporan bot sendiri yang belum terverifikasi. "Online" berarti bot melaporkan dirinya online, bukan hasil pemeriksaan independen.
  • Kontrak bot beku: bot tidak pernah memanggil /api/*, hanya PostgREST langsung. Format snapshot, fase setup_status, format key 32 hex, anon key sebagai query param, dan retry PGRST202 tidak berubah.
  • Angka pemakaian dan rating berasal dari RPC dan tabel nyata. Bila sumber belum ada, endpoint menjawab kosong atau 503 yang jujur, bukan angka karangan.