Lompat ke konten utama
StableTerakhir diperbarui: 9 Okt 2026, 09.28

API Playground

Playground memungkinkan Anda mengirim permintaan nyata ke API langsung dari halaman ini tanpa alat eksternal seperti Postman atau cURL. Fasilitas pengujian interaktif ini dirancang untuk menjembatani kesenjangan antara teori dokumentasi dan praktik integrasi, mempercepat siklus pengujian bagi tim pengembang Anda secara drastis. Dengan antarmuka yang terintegrasi secara mulus ke dalam setiap halaman dokumentasi yang relevan, para insinyur perangkat lunak dapat secara empiris memvalidasi struktur payload permintaan, skema keamanan, serta bentuk balasan server seketika itu juga, tepat di samping penjelasan konseptual mengenai endpoint tersebut.

Arsitektur sistem Playground kami dibangun dengan mengedepankan isolasi lingkungan dan mitigasi kerentanan lintas-situs (Cross-Site Request Forgery). Permintaan tidak pernah dikirimkan secara mentah melintasi domain yang berbeda (CORS), melainkan disalurkan melalui jalur reverse proxy internal yang terpercaya. Hal ini menjamin bahwa kredensial otorisasi yang Anda berikan hanya eksis di dalam lapisan memori sementara (volatile state) pada peramban web klien, dan tidak akan pernah dicegat atau disimpan oleh server peladen statis penyedia halaman dokumentasi ini.

Stable

1. Ikhtisar & Nilai Bisnis

Fasilitas API Playground memberikan keunggulan kompetitif yang signifikan bagi mitra integrator dan penyewa layanan (tenant) platform DagangBot AI. Kehadirannya bukan sekadar pelengkap visual, melainkan sebuah instrumen rekayasa perangkat lunak yang dioptimalkan untuk mengurangi waktu adaptasi dan meminimalkan galat (error) saat proses pemrograman klien. Nilai bisnis utama meliputi:

  • Pengujian Instan Berbasis Konteks: Memungkinkan pengembang melakukan validasi endpoint dan bentuk balasan API secara seketika tanpa keharusan meninggalkan halaman dokumentasi atau melakukan pengaturan awal (setup) lingkungan pengujian khusus seperti halnya konfigurasi koleksi Postman yang memakan waktu.
  • Keamanan Melalui Isolasi (Secure by Default): Seluruh rute permintaan yang diinisiasi oleh Playground dikirimkan ke origin dokumentasi itu sendiri (khususnya path /api/v1/*), untuk selanjutnya diteruskan menuju klaster backend sesungguhnya melalui pola reverse proxy yang tangguh. Mekanisme ini menghapuskan seluruh kompleksitas terkait Cross-Origin Resource Sharing (CORS) yang lazim mengganggu.
  • Interaktivitas Bebas Modifikasi: Blok JSON body, header tambahan, serta parameter path pada URL (seperti variabel dinamis {id}) dapat diedit dan dimodifikasi langsung melalui antarmuka grafis yang intuitif. Hal ini amat berguna untuk merekayasa kondisi edge-case tanpa perlu memodifikasi baris kode aplikasi Anda.
  • Jembatan Edukasional yang Solid: Di balik setiap pengujian interaktif, Playground menyertakan padanan skrip curl aktual yang merepresentasikan permintaan jaringan Anda secara presisi. Blok sintaksis curl tersebut dapat langsung disalin ke antarmuka baris perintah (terminal) Anda, memudahkan transisi dari pengujian visual menuju skrip otomatisasi di dalam pipa Continuous Integration (CI).
Lingkungan Eksekusi Nyata

Harap dicatat dengan seksama bahwa Playground ini memanggil klaster peladen backend produksi secara nyata (live). Apabila Anda mengeksekusi metode mutasi data, seperti POST, PUT, PATCH, atau DELETE, menggunakan kunci API dari lingkungan produksi, maka seluruh perubahan tersebut akan tercermin pada pangkalan data operasional Anda seketika itu juga. Anda disarankan untuk menggunakan token sesi uji coba atau kunci API khusus (sandbox key) saat melakukan eksperimen mutasi.

2. Alur Visual & Antarmuka

Antarmuka pengguna API & RAG Playground dirancang secara khusus untuk memfasilitasi pengujian langsung model AI, retrieval basis pengetahuan, dan endpoint integrasi secara interaktif:

Tampilan antarmuka RAG & API Playground interaktif DagangBot
Antarmuka interaktif Playground DagangBot untuk menguji retrieval konteks RAG, evaluasi prompt, dan respons model AI secara realtime.

Di atas merupakan contoh representasi antarmuka standar dari instans Playground. Bagian kiri memuat formulir input dinamis (berdasarkan inspeksi path untuk mendeteksi placeholder kurung kurawal), sedangkan bagian bawah memuat panel eksekusi dan modal konfirmasi untuk metode yang merusak atau memodifikasi state sistem.

3. Panduan Langkah-demi-Langkah

Untuk memaksimalkan utilitas dari alat ini, ikutilah panduan operasional langkah demi langkah berikut. Panduan ini menjelaskan prosedur dari tahap preparasi kredensial keamanan hingga inspeksi mutakhir atas rincian header HTTP yang dibalas oleh server.

  1. 1

    Langkah 1: Tentukan Endpoint dan Identifikasi Parameter

    Carilah komponen interaktif <ApiPlayground> pada halaman dokumentasi referensi terkait. Perhatikan secara saksama jika path URL memuat variabel dinamis yang ditandai oleh sepasang kurung kurawal (sebagai contoh: /api/v1/orders/{id}). Anda wajib mengisi nilai pengganti untuk variabel parameter URL tersebut pada kolom teks yang disediakan oleh antarmuka; kolom tersebut umumnya akan disorot warna kemerahan apabila masih dibiarkan kosong, mencegah transmisi request yang tidak utuh.

  2. 2

    Langkah 2: Atur Kredensial Otentikasi (Bila Disyaratkan)

    Sistem kami mendeteksi secara otomatis apakah suatu operasi membutuhkan lapisan pelindung keamanan, baik berupa BearerAuth (memanfaatkan JWT) maupun ApiKeyAuth (memanfaatkan kunci statis X-API-Key). Jika skema tersebut terdeteksi, sebuah kolom input tambahan untuk menyematkan kredensial akan muncul. Masukkan token atau kunci rahasia Anda pada kolom keamanan tersebut. Sistem dijamin tidak akan pernah menyimpan nilai sensitif ini pada kuki (cookies) atau ruang penyimpanan persisten (local storage); token Anda secara ketat dijaga agar hanya bernaung di dalam memori eksekusi peramban untuk durasi sesi yang sedang berjalan.

  3. 3

    Langkah 3: Modifikasi Body (Khusus Metode Mutasi)

    Untuk pemanggilan metode yang melibatkan pengiriman payload substansial, seperti POST, PUT, atau PATCH, Anda perlu menyesuaikan dan merekayasa parameter JSON pada fasilitas teks editor terintegrasi yang telah kami sediakan. Editor ini mendukung pewarnaan sintaksis. Sebagai latihan awal, cobalah mengirimkan payload perintah broadcast menggunakan curl berikut di lingkungan lokal Anda, yang padanannya persis sama dengan apa yang terjadi di balik antarmuka:

    bash
    curl -X POST "https://dagangbot.web.id/api/v1/all-in-one/messages/send" \
      -H "X-API-Key: dgb_all_sandbox_xyz123" \
      -H "Content-Type: application/json" \
      -d '{
        "phone_number": "6281234567890",
        "message": "Selamat datang di simulasi API Playground DagangBot AI!",
        "type": "text"
      }'
  4. 4

    Langkah 4: Persetujuan dan Eksekusi Permintaan

    Setelah meninjau keabsahan seluruh parameter, tekan tombol "Kirim Permintaan" yang terdapat di sisi kanan bawah komponen. Apabila metode yang dieksekusi memiliki dampak mutasi, mesin peramban Anda akan menampilkan sebuah kotak dialog (modal) peringatan konfirmasi. Hal ini merupakan palang pintu terakhir guna menghindari kecerobohan tak disengaja.

  5. 5

    Langkah 5: Analisis Respons dan Log HTTP

    Periksa secara cermat status code HTTP, blok header balasan, serta konstruksi JSON pada body respons yang dipaparkan oleh peladen. Jika Anda menemui kesulitan dalam menerjemahkan konfigurasi antarmuka ke skrip, Anda bisa dengan mudah menyalin blok kode curl yang secara dinamis dibangkitkan. Perhatikan bahwa Anda juga dapat memeriksa kesehatan layanan dasar (liveness) seperti yang direpresentasikan oleh contoh perintah di bawah ini:

    bash
    curl -X GET "https://dagangbot.web.id/api/v1/health" \
      -H "Accept: application/json"

Langkah 6: Eksperimen Pembatasan Kecepatan (Rate Limit)

Sebagai langkah lanjutan setelah menguasai dasar-dasar pemanggilan API, pengguna didorong untuk mencoba fitur ini guna memahami karakteristik penolakan Rate Limiting peladen. Anda dapat mencoba menekan tombol "Kirim Permintaan" berulang kali dalam jeda di bawah setengah detik secara berturut-turut pada salah satu endpoint pengiriman OTP atau transaksi lainnya.

Saat batas ambang keranjang token (Token Bucket) terlampaui, panel balasan tidak akan lagi memberikan format JSON reguler, melainkan akan menampakkan status 429 Too Many Requests. Amati bagian header yang dikembalikan oleh peladen; Anda akan menemukan kunci Retry-After yang mendikte jumlah detik tunggu sebelum blokade sementara (temporary IP lock) diangkat. Simulasi ini menanamkan kesadaran kritis bagi para pemrogram backend klien untuk wajib menerapkan mekanisme eksponensial mundur (Exponential Backoff) pada lapisan klien HTTP yang mereka bangun kelak.

4. Parameter & Spesifikasi Teknis

Di tingkat arsitektural internal, integrasi Playground dikendalikan oleh pemanggilan komponen antarmuka React dengan penamaan <ApiPlayground />. Desainer sistem dokumentasi (technical writer) memanfaatkan komponen ini dengan menyuplai deretan properti konfigurasi. Tabel berikut membeberkan secara definitif spesifikasi props beserta ekuivalen tipe data TypeScript-nya.

Properti Komponen Tipe Data TypeScript Penjelasan Komprehensif Fungsionalitas
method HttpMethod Mendefinisikan semantik metode HTTP yang valid (GET, POST, PUT, PATCH, DELETE). Penentuan ini memengaruhi kemunculan editor body dan modal konfirmasi.
path string Segmen path rute relatif terhadap proksi peladen, contohnya /health atau /orders/{id}. Fungsi internal regex secara otomatis meracik daftar variabel dari kurung kurawal.
summary string (Opsional) Penjelasan tekstual ringkas mengenai hakikat operasi yang akan direpresentasikan di tajuk panel komponen, menambah nilai pedagogis bagi pembaca.
security string[] Larik (array) skema otentikasi spesifikasi OpenAPI (contoh: ["BearerAuth"] atau ["ApiKeyAuth"]). Bila eksis, komponen akan merender bidang input password khusus kredensial.
defaultBody string Teks bersintaks JSON sebagai proforma dasar untuk memberikan gambaran kerangka struktur payload yang disarankan pada saat memfasilitasi operasi berjenis mutasi.
requiresAuth boolean (Usang) Tanda otentikasi lama; saat ini sangat dianjurkan untuk menggunakan pengaturan security yang jauh lebih spesifik sesuai kontrak keamanan OpenAPI.
className string Modifikasi penataan gaya spesifik instans (CSS override), umumnya digunakan untuk menyesuaikan tata letak komponen (margin, padding) terhadap alur paragraf.

Di samping struktur properti eksternal di atas, komponen secara mandiri (melalui fetch bawaan peramban) mengelola pemanggilan menuju /api/v1/... yang diproksikan secara transparan. Sistem secara ketat memberlakukan direktif inisialisasi jaringan credentials: "omit", yang mengebiri peramban agar menolak transmisi cookie berlabel sesi manajemen panel, meniadakan kemungkinan serangan pembajakan sesi.

Selain mekanisme pencegahan CORS dan pembatasan transmisi kuki otentikasi sesi melalui direktif credentials: "omit", arsitektur keamanan API Playground juga mengintegrasikan sistem pelacakan fingerprint temporal di lapisan perantara (middleware) kami. Peladen perantara ini akan senantiasa mengawasi kecepatan lalu lintas mutasi spesifik yang diinisiasi melalui origin domain dokumentasi. Praktik ini secara langsung membentengi peladen produksi utama (core services) dari risiko pembobolan atau pembanjiran data sampah yang berpotensi dihasilkan dari uji coba acak yang tak terawasi. Mekanisme ini memisahkan jejak memori sesi pada komponen penampil, memastikan tidak ada residu konfigurasi kunci API lintas-tab peramban pengguna.

Lebih jauh mengenai properti arsitektur reaktif komponen ini: kerangka kerja antarmukanya dibangun di atas pustaka React dengan memanfaatkan utilitas manajemen state termutakhir (seperti useMemo untuk proses parsial komputasi regex yang mahal, dan useState terisolasi pada setiap komponen instans untuk menahan isolasi silang variabel lingkungan). Efisiensi rendering inilah yang memungkinkan satu halaman dokumentasi yang panjang, semisal rujukan All-in-One API, memuat puluhan instans komponen Playground secara bersamaan tanpa sedikit pun mendegradasi kemulusan pengalaman menjelajah atau memicu lonjakan konsumsi memori gawai peramban pengguna. Kode sumber komponen berfokus pada reduksi re-render tak perlu saat pengguna mengetik panjang pada editor JSON bawaan.

Kapasitas interkoneksi ekosistem ini menjadikan API Playground sebagai salah satu instrumen rekayasa perangkat lunak paling bernilai dalam fase eksperimentasi tenant. Ketika seorang pengembang mencoba mereplikasi galat yang terjadi di perangkat mereka, tim pendukung pelanggan kami sering kali menyarankan perekonomian ulang permintaan secara identik melalui fasilitas ini guna memastikan apakah anomali tersebut merupakan kekeliruan sintaks aplikasi lokal pengembang, ataukah memang berupa inkompatibilitas murni yang bersumber dari internal ekosistem peladen pusat platform AI ini. Kemampuan replikasi yang sangat identik dan andal ini pada akhirnya memangkas drastis siklus pelaporan kutu (bug tracking cycle) berkat isolasi variabel perantara. Interaksi ini pada hakikatnya meminimalkan gesekan teknis yang biasanya hadir saat onboarding integrator baru dari perusahaan eksternal ke lingkungan API DagangBot.

5. Relasi & Integrasi

Detail Jembatan Pengecualian Jaringan (Reverse Proxy Transport)

Dalam menopang fungsionalitas pengujian ini, infrastruktur DagangBot mengimplementasikan pola penyalur balik (Reverse Proxy) terdedikasi pada rute /api/v1/* yang bernaung di bawah domain pelayan situs dokumentasi. Pelayan proksi ini bertindak selaku gerbang pembersih, yang secara selektif membuang seluruh header HTTP standar yang diinjeksi oleh peramban klien, seperti Origin dan Referer, sebelum paket dikirimkan ke peladen produksi inti. Hal ini meniadakan sepenuhnya anomali blokir kebijakan lintas asal (Cross-Origin Resource Sharing / CORS). Selain itu, proksi perantara ini dikonfigurasi untuk secara otomatis menyuntikkan header telemetri pelacakan internal tambahan, memastikan bahwa segala aktivitas uji coba dapat diaudit di kemudian hari secara komprehensif tanpa harus merusak struktur request murni buatan klien itu sendiri. Keberadaan jembatan khusus ini memungkinkan pengujian presisi di lingkungan dokumentasi tanpa membebani peramban.

Infrastruktur Playground merupakan komponen tulang punggung dalam menyajikan Referensi REST API menjadi ensiklopedia yang dapat dieksekusi secara nyata, alih-alih menjadi sekadar brosur pasif. Keterkaitan fungsionalnya juga membentang pada klaster manajemen Autentikasi & Otorisasi. Setiap interaksi dalam modul Playground mensimulasikan persis mekanisme otorisasi yang akan dilakukan oleh pustaka kode yang kelak disusun oleh klien. Semua hasil simulasi ini pada dasarnya berinteraksi mutlak dengan seluruh pilar operasional DagangBot AI.

6. Pemecahan Masalah (Troubleshooting)

Tabel berikut menyajikan kendala-kendala umum yang mungkin menginterupsi kelancaran eksperimen jaringan Anda dalam Playground, beserta akar penyebab dan jalan keluar solutifnya.

Gejala Galat Sistem Analisis Penyebab Utama Solusi Penanganan Rekomendatif
Tombol "Kirim Permintaan" membeku atau tak bisa diklik Masih ada segmen parameter dinamis, misal {id} atau {order_id}, pada baris formulir path yang dibiarkan kosong oleh pengguna. Isi setiap nilai parameter proksimal variabel URL yang teridentifikasi oleh sorotan garis luar berwarna merah terang.
Permintaan ditolak mentah-mentah dengan balasan status 401 Identitas token statis tidak valid secara kriptografis, atau kemungkinan besar sesi tenggang waktu kredensial (JWT) telah kedaluwarsa secara masif. Segarkan sesi Anda di portal Dashboard, bangkitkan ulang token atau kunci API, lalu sematkan kembali string otentikasi yang baru ke panel.
Eksekusi tertahan oleh peringatan sintaks JSON Terdapat inkonsistensi struktur, misalnya kelebihan tanda koma (trailing comma), ketiadaan penutup kurung, atau atribusi string tanpa tanda kutip di kolom body. Telaah payload JSON dengan perangkat linter atau alat pemformatan data terpusat, dan hapus anomali pemicu kebingungan parser.
Transmisi gagal total (dikenal sebagai Network Error bisu) Sambungan putus akibat ekstensi pembatas iklan (AdBlocker, Privacy Badger) yang secara agresif mencurigai arus keluar dari modul komponen non-standar antarmuka web. Berikan pengecualian sementara pada ekstensi mitigasi pelacakan (whitelist origin) untuk secara spesifik mengizinkan interaksi situs dokumentasi kita.
Residu manipulasi tetap tercermin kendati refresh layar Fakta bahwa operasi yang dieksekusi melalui antarmuka Playground berimbas secara definitif pada ekosistem peladen produksi, bukan sekadar basis data bohongan. Lakukan pembersihan manual atas entitas percobaan pada Dashboard utama untuk mengeliminasi gangguan polusi data set nyata Anda.

7. Kode Error & Penanganan

Matriks di bawah ini mendedah seluk-beluk respons kode kesalahan berskala global, merepresentasikan pola klasifikasi standar operasional dari arsitektur perlindungan sistem saat mendapati perintah-perintah malformasi yang memancar dari pengujian lokal Playground Anda.

Kode Status HTTP Kategori Simbolik Makna Penjabaran Tindakan Penanganan Khusus Eksternal
400 Bad Request Kekeliruan skema struktur. Muatan masukan, entah itu query string, tipe objek pada balok body, maupun absensi atribut wajib, sangat nyata menyimpang dari definisi skema endpoint. Analisis proksi kesalahan mendetail pada simpul details balasan JSON; perbaiki masukan parameter cacat dari formulir editor UI.
401 Unauthorized Autentikasi bobol atau kosong. Pertahanan siber perimeter peladen memastikan komponen tidak menyertakan tanda pengenal valid pada bilah header protokol pertukaran (X-API-Key atau Authorization). Tempelkan serangkaian kode API Key sahih yang bernaung dari tenant tersertifikasi milik Anda, dan berhati-hatilah agar tidak menempel spasi ekstra.
403 Forbidden Eksklusi otoritas. Meskipun sandi Anda valid secara matematis, kapabilitas wewenang peran (role scopes) yang dimandatkan padanya tidak memadai bagi beban kerja rute yang hendak dirambah. Mintalah kepada administrator super pemilik tenant untuk memperluas dan mengonfigurasikan ulang jangkauan perizinan kunci API bersangkutan.
404 Not Found Kegagalan penemuan sumber. Entitas penunjuk acuan (seperti parameter ID bernomor seri di badan penulisan URL eksplisit) tidak berkorespondensi dengan objek nyata apa pun di lapisan persisten backend. Selidik kembali direktori penyimpanan dan pastikan presisi ID unik identifikasi telah Anda susun dengan saksama tanpa pengurangan digit satu pun.
429 Too Many Requests Pengereman kuota masif. Anda telah menekan tuas eksekusi dengan rentetan frekuensi tinggi secara terus-menerus hingga memprovokasi bangkitnya perisai pembatas laju pemanggilan sirkuit. Hentikan operasi yang membabi-buta sesaat. Evaluasi kembali siklus dan pola back-off skrip Anda sembari menunggu relaksasi sirkuit pemutus laju pulih dalam menit berikutnya.
500 Internal Server Kegagalan tak tertangani. Kecacatan proses fatal menimpa komputasi di sisi peladen (kemungkinan karena database timeout atau kepanikan program peladen secara inheren). Catatlah nomor identifikasi pelacakan error (apabila disematkan) dan teruskan laporan anomali insiden sistem tersebut ke portal sokongan teknis spesialis dukungan pelanggan kami.

8. Referensi Terkait

content/docs/integrations/playground.mdx
Terakhir diperbarui: 9 Okt 2026, 09.28

Dokumentasi teknis DagangBot