Tidak suka iklan? Pergi Bebas Iklan Hari ini 

Pengkodean URL Apa yang Dibuang dan Mengapa API Anda Tidak Bisa Berfungsi Tanpa Ini

Diterbitkan pada 25 Apr 2026

URL Encoding: Apa yang Dibuang dan Mengapa API Anda Tidak Bisa Berfungsi Tanpa Ini 1

IKLAN · HAPUS?

Panggilan API Anda tampak benar. Endpoint cocok, header benar, dan respons kembali 400 Bad Request. Setelah dua puluh menit memandangnya, Anda menemukan masalah: alamat email dalam string query yang mengandung sebuah + tanda — yang di-decode oleh server sebagai spasi. Ini adalah tindakan URL encoding, dan hal ini menghancurkan sesuatu dengan cara yang benar-benar sulit untuk didebug.

Panduan ini menjelaskan apa yang sebenarnya dilakukan oleh percent-encoding, karakter apa yang harus di-encode dalam konteks apa, perangkap JavaScript yang sering dihadapi, dan cara menggunakan alat seperti URL Encoder/Decoder untuk memeriksa pekerjaan Anda.

Apa yang Dilakukan URL Encoding Sebenarnya

URL hanya dapat mengandung subset karakter ASCII. Semua yang lain — spasi, karakter internasional, simbol yang memiliki makna khusus dalam URL — harus dikonversi ke format aman sebelum dikirim.

Percent-encoding melakukan ini dengan mengganti setiap byte yang tidak aman dengan tanda persen diikuti dua digit heksadesimal. Spasi menjadi %20, tanda hash menjadi %23, garis miring menjadi %2F. Nama ini berasal dari tanda persen di awal.

Spesifikasi (RFC 3986) mendefinisikan karakter "yang tidak perlu dienkripsi" yang tidak perlu dienkripsi: huruf (A-Z, a-z), angka (0-9), dan empat simbol: - _ . ~. Semua yang lainnya adalah karakter yang terbatas (digunakan untuk membagi struktur URL) atau harus dienkripsi.

Karakter yang Menghancurkan API

Berikut adalah yang paling menyebabkan kerusakan dalam praktik:

Karakter	Terkodekan	Konteks yang membutuhkan enkripsi	Catatan
Ruang angkasa	%20	Semua konteks	Juga dienkripsi sebagai `+` dalam data form — lihat di bawah
&	%26	Nilai string query	Memisahkan parameter query; harus dienkripsi di dalam nilai
=	%3D	Nilai string query	Memisahkan kunci dari nilai; enkripsi di dalam nilai itu sendiri
+	%2B	Nilai string query	Didekripsi sebagai spasi dalam enkripsi form — gunakan `%2B` untuk tanda plus literal
#	%23	Path, string query	Menandai fragmen; apa pun yang ada setelahnya tidak dikirim ke server
?	%3F	Segment path, nilai query	Memulai string query; enkripsi di dalam path atau nilai
/	%2F	Segment path (ketika literal)	Memisahkan segment path; enkripsi di dalam nilai segment
@	%40	Nilai string query	Alamat email dalam parameter query harus dienkripsi seperti ini

Tiga Konteks, Aturan yang Berbeda

Bagian URL yang Anda enkripsi mengubah apa yang harus di-escape.

URL Penuh — Ketika Anda memiliki URL lengkap yang harus dipindahkan, Anda ingin mempertahankan strukturnya. Garis miring, tanda tanya, dan tanda hash tetap seperti semula. Hanya karakter di luar himpunan yang diizinkan yang dienkripsi.

Nilai string query — Ini adalah tempat di mana kebanyakan bug API terjadi. Setiap nilai dalam string query harus dienkripsi sehingga karakter yang digunakan untuk membangun struktur query (&, =, #, +) tidak muncul secara literal di dalam nilai. Jika nama pengguna adalah "John & Jane", string query harus membaca name=John%20%26%20Jane, bukan name=John & Jane (yang dipecahkan oleh server sebagai dua parameter terpisah).

Segment path — Segment path adalah bagian antara garis miring. Jika sebuah segment mengandung garis miring sendiri (misalnya, nama file dengan garis miring), maka harus dienkripsi sebagai %2F. Beberapa server menganggap %2F dalam path sebagai kekhawatiran keamanan; ketahui backend Anda sebelum menggunakan ini.

encodeURI vs encodeURIComponent — Perangkap JavaScript

JavaScript memberi Anda dua fungsi enkripsi bawaan, dan menggunakan yang salah adalah bug yang sangat umum.

// encodeURI — encodes a full URL
// Preserves: : / ? # [ ] @ ! $ & ' ( ) * + , ; =
encodeURI("https://example.com/search?q=hello world&lang=en")
// → "https://example.com/search?q=hello%20world&lang=en"
// Note: & and = are NOT encoded — the query structure is preserved

// encodeURIComponent — encodes a single value
// Encodes everything except: A-Z a-z 0-9 - _ . ! ~ * ' ( )
encodeURIComponent("hello world&lang=en")
// → "hello%20world%26lang%3Den"
// Note: & and = ARE encoded — safe to use as a query value

// The bug: using encodeURI on a value
encodeURI("hello world&lang=en")
// → "hello%20world&lang=en"  ← & survives! Server sees two parameters.

// The correct approach for building query strings
const name = "John & Jane"
const email = "john+jane@example.com"
const url = `https://api.example.com/users?name=${encodeURIComponent(name)}&email=${encodeURIComponent(email)}`
// → "https://api.example.com/users?name=John%20%26%20Jane&email=john%2Bjane%40example.com"

Aturan umum: gunakan encodeURIComponent pada nilai individu sebelum dimasukkan ke dalam URL. Gunakan encodeURI hanya ketika Anda memiliki URL lengkap dan ingin membersihkannya tanpa merusak strukturnya.

Tanda Plus: Enkripsi Form vs Percent Encoding

Ketika formulir HTML mengirimkan data dengan method="GET", browser menggunakan application/x-www-form-urlencodeduntuk mengenkripsi data tersebut. Dalam format ini, spasi menjadi + alih-alih %20. Banyak kerangka server (PHP, Django, Rails) secara otomatis mendekode + sebagai spasi dalam string query.

Ini menciptakan masalah ketika nilai Anda secara sah mengandung tanda plus — seperti nomor telepon +44 7700 900000. Jika Anda mengirimkannya sebagai +44..., server akan mendekode tanda plus di awal sebagai spasi dan mendapatkan 44.... Solusinya adalah mengenkripsi tanda plus literal sebagai %2B, yang tetap utuh dalam kedua skema dekripsi tersebut.

Untuk pekerjaan API modern, gunakan %20 untuk spasi (yang dihasilkan oleh encodeURIComponent ) daripada mengandalkan +.

Duble-Enkripsi: Ketika Enkripsi Salah

Duble-enkripsi terjadi ketika Anda mengenkripsi sesuatu yang sudah dienkripsi. Tanda persen dalam %20 sendiri dienkripsi menjadi %2520 — server mendekode %25 ke dalam tanda persen literal, memberikan string %20 sebagai ganti spasi.

Ini biasanya muncul ketika:

Anda menyimpan URL di database dan mengenkripsi ulang sebelum menggunakan
Framework atau library mengenkripsi nilai yang sudah Anda enkripsi secara manual
Anda membuat URL yang mengandung URL lain sebagai parameter

Untuk menghindarinya: enkripsi tepat sekali, pada titik Anda menyusun URL. Jika Anda tidak yakin apakah nilai sudah dienkripsi, dekripsi dulu (dengan decodeURIComponent), lalu enkripsi ulang secara bersih.

Pemantauan URL Enkripsi di DevTools

Ketika permintaan API berperilaku tidak sesuai, buka DevTools (F12), pindah ke tab Network, dan klik permintaan yang gagal. Di bagian Headers, cari URL Permintaan — browser menampilkan bentuk mentah setelah enkripsi. Di bagian Payload, Anda dapat melihat parameter query yang telah didekripsi kembali ke nilai aslinya, yang memudahkan Anda melihat apakah tanda ampersand dianggap sebagai pemisah atau dikirim sebagai nilai literal.

Untuk pengujian manual, alat online untuk enkripsi dan dekripsi URL memungkinkan Anda menempelkan string dan melihat bentuk yang dienkripsi — berguna untuk memeriksa nilai sebelum dimasukkan ke dalam permintaan. Alat IO Tools URL Encoder/Decoder mengelola kedua arah dan menampilkan hasilnya secara langsung.