Best Practices für URL-Encoding in REST-APIs

Warum URL-Encoding für APIs wichtig ist

Korrektes URL-Encoding ist bei der REST-API-Entwicklung von entscheidender Bedeutung. Falsch kodierte URLs können zu fehlerhaften Requests, Sicherheitslücken, Datenverlust und Interoperabilitätsproblemen zwischen verschiedenen Systemen und Programmiersprachen führen. Als API-Entwickler musst du sowohl verstehen, wie du URLs beim Senden von Requests kodierst, als auch, wie du sie beim Verarbeiten von Requests dekodierst.

Pfadparameter kodieren

REST-APIs verwenden häufig Pfadparameter, um Ressourcen zu identifizieren. Wenn diese Parameter Sonderzeichen enthalten, ist eine korrekte Kodierung unerlässlich:

// Pfadparameter mit Sonderzeichen
// Ressource: "Tom & Jerry's Show"
GET /api/shows/Tom%20%26%20Jerry%27s%20Show

// Mit JavaScript
const showName = "Tom & Jerry's Show";
const url = `/api/shows/${encodeURIComponent(showName)}`;

// Pfad mit Schrägstrich im Wert
// Datei: "documents/my report.pdf"
GET /api/files/documents%2Fmy%20report.pdf

Query-Parameter kodieren

Query-Parameter sind die häufigste Stelle, an der Encoding-Probleme auftreten. Kodiere immer sowohl Schlüssel als auch Werte:

// Mehrere Parameter mit Sonderzeichen
GET /api/search?q=C%2B%2B%20programming&category=languages%20%26%20tools&page=1

// Mit URLSearchParams (empfohlen)
const params = new URLSearchParams({
  q: 'C++ programming',
  category: 'languages & tools',
  page: '1'
});
const url = '/api/search?' + params.toString();

Arrays und Objekte in Query-Strings verarbeiten

Verschiedene API-Frameworks verarbeiten Array-Parameter unterschiedlich. Hier sind die gängigen Konventionen:

// Wiederholte Schlüssel (am häufigsten)
GET /api/items?tag=javascript&tag=typescript&tag=react

// Bracket-Notation (PHP, Rails)
GET /api/items?tags[]=javascript&tags[]=typescript

// Kommagetrennt (einige REST-APIs)
GET /api/items?tags=javascript,typescript,react

// Verschachtelte Objekte (Bracket-Notation)
GET /api/search?filter[status]=active&filter[sort]=date

Content-Type und Encoding

Der Content-Type-Header bestimmt, wie die Daten im Request-Body kodiert werden:

• application/x-www-form-urlencoded – Ähnlich wie URL-Query-Strings. Schlüssel und Werte werden kodiert, Leerzeichen werden zu +
• multipart/form-data – Wird für Datei-Uploads verwendet. Jeder Teil hat seine eigene Kodierung
• application/json – JSON-Format. Für den Body ist kein URL-Encoding nötig, aber der Content-Type muss korrekt gesetzt werden

Sicherheitsaspekte bei APIs

• Validiere und bereinige dekodierte URL-Parameter immer auf dem Server
• Achte auf Path-Traversal-Angriffe über kodierte Sequenzen wie %2e%2e%2f (../)
• Implementiere Längenbeschränkungen für URLs, um Denial-of-Service-Angriffe zu verhindern
• Vertraue niemals der clientseitigen Kodierung – validiere immer erneut auf dem Server
• Achte auf Double-Encoding-Angriffe, bei denen bösartige Eingaben nach einer Dekodierungsrunde Filter umgehen
• Verwende parametrisierte Abfragen, um SQL-Injection auch nach dem URL-Decoding zu verhindern

URL-Encoding in APIs testen

Berücksichtige beim Testen deiner API-Endpunkte Testfälle für die folgenden Szenarien:

• Parameter mit Leerzeichen (teste sowohl %20 als auch +)
• Parameter mit reservierten Zeichen (&, =, ?, #)
• Parameter mit Unicode-Zeichen
• Leere Parameterwerte
• Sehr lange Parameterwerte
• Bereits kodierte Eingaben (Erkennung von Double-Encoding)
• Parameter mit Null-Bytes (%00)