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+ headerRetry-After: 60+X-RateLimit-Remaining. - 503 dibedakan:
MIGRATION_MISSINGbila migrasi database belum diterapkan,UPSTREAM_UNAVAILABLEbila database tidak terjangkau,WRITE_FAILEDbila tulis terverifikasi gagal. - Body request POST dibatasi 256 KiB. Lebih dari itu dijawab 413
BODY_TOO_LARGEsebelum 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
GET/api/templates
- Auth
- Tidak ada
- Rate limit
- 60/menit per IP (per instance)
- Sukses
{ templates }- Error
- 429
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
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
GET/api/marketplace
- Auth
- Tidak ada
- Rate limit
- 60/menit per IP (per instance)
- Sukses
{ ok: true, data: { usage, ratings } }- Error
- 429
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
GET/api/bot-status
- Auth
- Tidak ada
- Rate limit
- 60/menit per IP (per instance)
- Sukses
{ state, last_seen }- Error
- 429
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
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
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
GET/api/favorites
- Auth
- Sesi login
- Rate limit
- 60/menit per IP (per instance)
- Sukses
{ ok: true, data: string[] }- Error
- 401 UNAUTHORIZED, 429, 503
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
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
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
GET/api/notifications
- Auth
- Sesi login
- Rate limit
- 60/menit per IP (per instance)
- Sukses
{ ok: true, notifications }- Error
- 401 UNAUTHORIZED, 429
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
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
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
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
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
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.