URL-Encoding Komplett Verstehen

"Ich habe Parameter an die API gesendet und sie kamen beschadigt zuruck."

Gesendet: ?name=Max Mustermann
Empfangen: ?name=Max%20Mustermann

Die Ursache dieses Problems ist URL-Encoding. Wenn Sie es richtig verstehen, werden Sie nie wieder mit beschadigten Zeichen kampfen.

---

Warum Encoding notwendig ist

URLs wurden in den 1990er Jahren erstellt und erlauben nur ASCII-Zeichen.

Sichere Zeichen in URLs

A-Z  a-z  0-9  - _ . ~

Das ist alles.

Problematische Zeichen in URLs

Was Encoding macht

Konvertiert problematische Zeichen in das Format %XX (Hexadezimal).

Leerzeichen -> %20
&           -> %26
u           -> %C3%BC (z.B. fur u)

---

JavaScript-Encoding-Funktionen

Hauptunterschiede

const text = "hello world&name=Max Mustermann";

encodeURI(text);
// "hello%20world&name=Max%20Mustermann"
// & und = bleiben intakt (URL-Struktur erhalten)

encodeURIComponent(text);
// "hello%20world%26name%3DMax%20Mustermann"
// & -> %26, = -> %3D (alles kodiert)

Wann was verwenden

Haufige Fehler

// Falsch: encodeURIComponent auf gesamte URL
const url = "https://api.com/search?q=Test";
encodeURIComponent(url);
// "https%3A%2F%2Fapi.com%2Fsearch%3Fq%3DTest"
// Nicht als URL verwendbar!

// Richtig: Nur den Wert kodieren
const query = "Test";
const url = `https://api.com/search?q=${encodeURIComponent(query)}`;
// "https://api.com/search?q=Test"

---

URLSearchParams - Der moderne Weg

Verwenden Sie URLSearchParams statt manueller Kodierung.

Grundlegende Verwendung

const params = new URLSearchParams({
  name: "Max Mustermann",
  city: "Munchen",
  tags: "Entwickler,Frontend"
});

params.toString();
// "name=Max+Mustermann&city=M%C3%BCnchen&tags=Entwickler%2CFrontend"

Die Kodierung erfolgt automatisch. Kein Raum fur Fehler.

Mit URL-Objekt

const url = new URL("https://api.com/search");
url.searchParams.set("q", "Max Mustermann");
url.searchParams.set("page", 1);

url.toString();
// "https://api.com/search?q=Max+Mustermann&page=1"

Parsing (Dekodierung)

const url = new URL("https://api.com/search?name=Max%20Mustermann");

url.searchParams.get("name");  // "Max Mustermann" <- automatisch dekodiert!

---

Praktische Problemlosung

Problem 1: Doppelte Kodierung

// Einen bereits kodierten Wert erneut kodieren
const encoded = "%20";
encodeURIComponent(encoded);
// "%2520"
// % -> %25 verursacht vollstandige Beschadigung

Losung: Vor dem Kodieren prufen, ob bereits kodiert

function safeEncode(str) {
  try {
    // Wenn bereits kodiert, erst dekodieren dann neu kodieren
    return encodeURIComponent(decodeURIComponent(str));
  } catch {
    // Dekodierungsfehler = noch nicht kodiert
    return encodeURIComponent(str);
  }
}

Problem 2: Zwei Gesichter des Leerzeichens

%20  vs  +

Beide reprasentieren Leerzeichen, haben aber unterschiedliche Ursprunge.

encodeURIComponent("hello world");  // "hello%20world"
new URLSearchParams({q: "hello world"}).toString();  // "q=hello+world"

Beide werden von Servern korrekt verarbeitet. Aber wahlen Sie eine Methode fur Konsistenz.

Problem 3: Framework kodiert bereits

axios, fetch, React Router, usw. kodieren automatisch.

// axios - automatische Kodierung
axios.get('/search', { params: { name: 'Max Mustermann' } });
// Anfrage: /search?name=Max%20Mustermann

// Falsch: Manuelle Kodierung verursacht doppelte Kodierung
axios.get('/search', { params: { name: encodeURIComponent('Max Mustermann') } });
// Anfrage: /search?name=Max%2520Mustermann (beschadigt)

Regel: Wenn Sie ein Framework verwenden, kodieren Sie nicht manuell.

---

Serverseitige Behandlung

Node.js / Express

// Automatisch dekodiert
app.get('/search', (req, res) => {
  const name = req.query.name;  // "Max Mustermann"
});

// Gleich fur Pfadparameter
app.get('/users/:name', (req, res) => {
  const name = req.params.name;  // "Max Mustermann"
});

Python / Flask

from flask import request

@app.route('/search')
def search():
    name = request.args.get('name')  # "Max Mustermann"

PHP

$name = $_GET['name'];  // "Max Mustermann"
// PHP dekodiert auch automatisch

---

Spezialfalle

Base64 in URL

Standard-Base64 enthalt +, /, =, die Probleme in URLs verursachen.

// Standard Base64
btoa("hello");  // "aGVsbG8="

// URL-sicheres Base64
function base64UrlEncode(str) {
  return btoa(str)
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/, '');  // Padding entfernen
}

base64UrlEncode("hello");  // "aGVsbG8"

JWT verwendet dieses Format.

Fragment (#) Vorsicht

https://example.com/page?name=Max#section
                                  ^
                        Wird ab hier nicht an Server gesendet

Alles nach # (Fragment) wird nur im Browser verarbeitet und nicht an den Server gesendet.

---

Debugging-Tipps

Browser-Adressleiste

Browser zeigen dekodierte URLs fur bessere Lesbarkeit.

Angezeigt: https://example.com/users/Max Mustermann
Tatsachlich: https://example.com/users/Max%20Mustermann

Uberprufen Sie die tatsachliche Anfrage-URL im Network-Tab der Entwicklertools.

Testen mit curl

# Direkt kodierte URL
curl "https://api.com/search?name=Max%20Mustermann"

# curl kodieren lassen
curl -G "https://api.com/search" --data-urlencode "name=Max Mustermann"

---

Zusammenfassung

Kernprinzip: Wann immer moglich, lassen Sie URLSearchParams oder Ihr Framework die Arbeit erledigen und vermeiden Sie manuelle Kodierung.

---

Verwandte Werkzeuge