Best practice per l'URL encoding nelle API REST

Perché l'URL encoding è importante per le API

Un URL encoding corretto è fondamentale nello sviluppo di API REST. URL codificati in modo errato possono causare richieste non funzionanti, vulnerabilità di sicurezza, perdita di dati e problemi di interoperabilità tra sistemi e linguaggi di programmazione diversi. In quanto sviluppatore di API, devi capire sia come codificare gli URL quando invii richieste, sia come decodificarli quando gestisci le richieste.

Codifica dei parametri di percorso

Le API REST usano spesso parametri di percorso per identificare le risorse. Quando questi parametri contengono caratteri speciali, una codifica corretta è essenziale:

// Parametro di percorso con caratteri speciali
// Risorsa: "Tom & Jerry's Show"
GET /api/shows/Tom%20%26%20Jerry%27s%20Show

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

// Percorso con barra nel valore
// File: "documents/my report.pdf"
GET /api/files/documents%2Fmy%20report.pdf

Codifica dei parametri di query

I parametri di query sono il punto in cui i problemi di codifica si presentano più di frequente. Codifica sempre sia le chiavi che i valori:

// Più parametri con caratteri speciali
GET /api/search?q=C%2B%2B%20programming&category=languages%20%26%20tools&page=1

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

Gestione di array e oggetti nelle query string

I diversi framework per API gestiscono i parametri di tipo array in modo differente. Ecco le convenzioni più comuni:

// Chiavi ripetute (più comune)
GET /api/items?tag=javascript&tag=typescript&tag=react

// Notazione con parentesi quadre (PHP, Rails)
GET /api/items?tags[]=javascript&tags[]=typescript

// Valori separati da virgola (alcune API REST)
GET /api/items?tags=javascript,typescript,react

// Oggetti annidati (notazione con parentesi quadre)
GET /api/search?filter[status]=active&filter[sort]=date

Content-Type e codifica

L'header Content-Type determina come vengono codificati i dati del corpo della richiesta:

• application/x-www-form-urlencoded - Simile alle query string degli URL. Chiavi e valori vengono codificati, gli spazi diventano +
• multipart/form-data - Usato per il caricamento di file. Ogni parte ha la propria codifica
• application/json - Formato JSON. Non è necessaria alcuna URL encoding per il corpo, ma il Content-Type deve essere impostato correttamente

Considerazioni sulla sicurezza delle API

• Convalida e sanifica sempre lato server i parametri URL decodificati
• Fai attenzione agli attacchi di path traversal tramite sequenze codificate come %2e%2e%2f (../)
• Imposta limiti alla lunghezza degli URL per prevenire attacchi denial-of-service
• Non fidarti mai della codifica lato client -- riconvalida sempre lato server
• Attenzione agli attacchi di doppia codifica, in cui input malevoli aggirano i filtri dopo un solo ciclo di decodifica
• Usa query parametrizzate per prevenire l'SQL injection anche dopo la decodifica dell'URL

Test dell'URL encoding nelle API

Quando testi gli endpoint della tua API, includi casi di test per i seguenti scenari:

• Parametri con spazi (testa sia %20 che +)
• Parametri con caratteri riservati (&, =, ?, #)
• Parametri con caratteri Unicode
• Valori di parametro vuoti
• Valori di parametro molto lunghi
• Input già codificato (rilevamento della doppia codifica)
• Parametri con byte null (%00)