Inviare file a un’API: multipart o Base64 e come evitare caricamenti danneggiati

È l’endpoint a decidere come inviare il file

Inviare un file a un’API significa includerne il contenuto in una richiesta HTTP che il server possa interpretare. Non esiste un formato universale valido per tutti gli endpoint: uno può aspettarsi un caricamento multipart/form-data, un altro un oggetto JSON con il contenuto codificato, un altro ancora un meccanismo diverso descritto nel relativo contratto. L’estensione del file o il fatto che una richiesta utilizzi POST non bastano per decidere quale struttura inviare. Il primo passo è identificare l’operazione specifica e attenersi a quanto dichiara.

Separare la rappresentazione del file dalla logica di business aiuta a diagnosticare i problemi. La rappresentazione determina come vengono trasmessi i byte e i campi; l’endpoint stabilisce quali campi richiede, quali tipi accetta e quale risposta restituisce. Se si invia un corpo valido per un’operazione diversa, il server può rifiutarlo o elaborarlo in modo imprevisto. Prima di scrivere codice, annota metodo, percorso, autenticazione, tipo di contenuto, campi obbligatori, limiti documentati e risposte di errore.

• Non dedurre il formato accettato dal nome del percorso né da un’integrazione di un altro fornitore.
• Considera gli esempi di richiesta come indicazioni, ma verifica che si riferiscano alla stessa versione e alla stessa operazione.

Multipart/form-data e Base64 in JSON

Con multipart/form-data, il corpo viene suddiviso in parti separate. Ogni parte ha le proprie intestazioni e il proprio contenuto, quindi una richiesta può combinare il file con campi aggiuntivi, se l’endpoint li supporta. Il client crea la separazione tra le parti; per questo, quando si usa una libreria HTTP, di norma è meglio lasciare che sia la libreria a generare l’intestazione Content-Type completa e il relativo delimitatore. Impostarla manualmente senza mantenere il delimitatore corrispondente al corpo è una causa frequente di richieste che il server non riesce ad analizzare.

Con Base64, i byte del file vengono convertiti in testo e quel testo viene inserito in un documento JSON, per esempio in una proprietà definita dal contratto. Questa rappresentazione richiede una codifica e una successiva interpretazione del contenuto. Non dare per scontati il nome della proprietà, l’eventuale prefisso del tipo di media o il fatto che l’endpoint accetti Base64: sono aspetti stabiliti dallo schema. Per i caricamenti di grandi dimensioni, confronta i costi e i limiti documentati prima di scegliere.

• Multipart è adatto quando il contratto descrive parti del modulo e una parte contenente il file.
• Base64 è un’opzione solo se l’endpoint dichiara questa rappresentazione; non basta che il corpo sia JSON.

Esaminare OpenAPI senza fare supposizioni

Consulta la specifica OpenAPI disponibile e individua l’operazione esatta usando il percorso e il metodo. Verifica il tipo di contenuto accettato dal corpo della richiesta, lo schema associato e le proprietà obbligatorie. Per multipart, controlla come viene dichiarato il file e quali nomi hanno le parti; per JSON, cerca la struttura e il tipo di dato indicati per ogni campo. La documentazione OpenAPI è importante perché l’accettazione di caricamenti multipart deve essere specificata nel contratto, non dedotta per intuizione.

Leggi anche le risposte documentate, i requisiti di autenticazione e ogni limite o restrizione associati all’operazione. Un esempio non documenta necessariamente tutti i casi validi, e l’assenza di informazioni non equivale al permesso di inviare file arbitrari. Se manca lo schema, il tipo di contenuto non è chiaro o le istruzioni sono contraddittorie, chiedi conferma al responsabile dell’API prima di scrivere il codice. Annota la versione del contratto utilizzata per l’implementazione e i test.

• Verifica metodo, percorso, Content-Type, schema del corpo, campi obbligatori e possibili risposte.
• Non dedurre limiti, autorizzazioni, formati accettati o modalità di archiviazione da una descrizione generale del prodotto.

Creare la richiesta ed evitare gli errori più comuni

In un esempio concettuale multipart, il client invia una parte con il nome del campo dichiarato dal contratto e il contenuto binario del file; può includere altre parti solo se sono documentate. In un esempio concettuale JSON, legge i byte, li codifica in Base64 e li inserisce nella proprietà esatta definita dallo schema. Questi esempi descrivono modelli, non una richiesta compatibile con uno specifico endpoint di Apification. L’integrazione di Apification include REST API e OpenAPI, ma le informazioni qui disponibili non specificano quale operazione accetti file né quale schema utilizzi.

Prima dell’invio, verifica che il file si apra correttamente e che il programma non stia leggendo un percorso errato, un file vuoto o una versione parziale. Non confondere il nome o l’estensione con il tipo MIME: potrebbero non corrispondere, e il valore da trasmettere dipende dal contratto. Evita di troncare Base64 quando registri le richieste o trasferisci JSON tra componenti. Controlla anche i limiti di dimensione nel client, nei componenti intermedi e nel server, perché un rifiuto può verificarsi prima che l’endpoint elabori il corpo.

• Errori tipici: nome del campo errato, JSON malformato, delimitatore multipart mancante, contenuto Base64 troncato e tipo MIME non accettato.
• Non registrare nelle tracce il contenuto completo del file; registra i metadati necessari per la diagnosi senza esporre il documento.

Verificare dall’inizio alla fine che il file non sia stato danneggiato

Una risposta HTTP di esito positivo non dimostra, da sola, che il contenuto archiviato corrisponda al file di origine. Progetta un test che invii un file rappresentativo e poi recuperi l’oggetto ricevuto tramite il meccanismo documentato dall’API. Se non esiste un modo documentato per recuperarlo, verifica quale controllo offre il servizio; non dare per scontato che la risposta contenga il file o che sia disponibile un’operazione di download. Conserva senza modifiche l’originale di prova e annotane la dimensione e, se il flusso lo consente, un’impronta calcolata localmente.

Confronta il file recuperato con l’originale mediante un confronto binario oppure calcolando la stessa impronta per entrambi. Esegui test con diversi tipi e dimensioni pertinenti all’integrazione, compresi file piccoli e file vicini al limite documentato. Controlla anche il codice di risposta, il corpo dell’errore e i log sicuri del client. Se il risultato è diverso, individua il punto in cui è avvenuta la modifica: lettura locale, codifica, trasporto, elaborazione del server o download successivo.

• Prova almeno un file binario e uno con contenuto testuale; includi nomi con spazi o caratteri non ASCII se il contratto lo consente.
• Ripeti con richieste che superano i limiti solo in un ambiente controllato e verifica che il rifiuto sia chiaro e non lasci un oggetto parziale.

Lista di controllo prima dell’integrazione

Prima del rilascio, trasforma il contratto in una lista verificabile: operazione e versione corrette, tipo di contenuto dichiarato, campi e nomi esatti, autenticazione richiesta, limiti noti e modalità di interpretazione delle risposte. Implementa la richiesta con una libreria che gestisca correttamente multipart oppure con una serializzazione JSON affidabile. Definisci cosa accade in caso di errori di rete, rifiuto per dimensione, credenziali non valide o risposta malformata. Ripetere automaticamente un caricamento non è sempre innocuo: determina se l’endpoint consente di ripeterlo senza creare duplicati o risultati ambigui.

Completa la revisione con i controlli operativi. Limita l’accesso al file di origine in base alle esigenze dell’integrazione, evita di includere credenziali o contenuti sensibili nei log ed elimina i file temporanei quando non servono più. Documenta come riprodurre un caricamento non riuscito con un file di prova e come verificare la ricezione. Apification offre l’integrazione di Cloud e dei suoi servizi tramite REST API, OpenAPI, webhook, iframe e JavaScript; i dettagli sul caricamento, le autorizzazioni e le funzionalità di ciascun endpoint devono essere confermati nella documentazione applicabile, non dedotti da questa capacità generale.

• Contratto verificato e versionato.
• Rappresentazione e limiti confermati per l’endpoint specifico.
• Test d’integrità, errori e tentativi ripetuti completati.
• Accesso, log e file temporanei verificati.

Domande frequenti