Envoyer des fichiers à une API : multipart ou Base64 et éviter les transferts corrompus

C’est l’endpoint qui détermine comment envoyer le fichier

Envoyer un fichier à une API consiste à inclure son contenu dans une requête HTTP que le serveur peut interpréter. Il n’existe pas de format universel adapté à tous les endpoints : l’un peut attendre un transfert multipart/form-data, un autre un objet JSON contenant du contenu encodé, et un troisième un mécanisme différent décrit dans son contrat. L’extension du fichier ou le fait qu’une requête utilise POST ne suffisent pas à déterminer quelle structure envoyer. La première étape consiste à identifier l’opération concernée et à suivre ce qu’elle déclare.

Distinguer la représentation du fichier de la logique métier facilite le diagnostic des problèmes. La représentation détermine comment les octets et les champs sont transmis ; l’endpoint détermine les champs requis, les types acceptés et la réponse produite. Si le corps envoyé est valide pour une autre opération, le serveur peut le rejeter ou le traiter de manière inattendue. Avant d’écrire du code, notez la méthode, la route, l’authentification, le type de contenu, les champs obligatoires, les limites documentées et les réponses d’erreur.

• Ne déduisez pas le format accepté à partir du nom de la route ou d’une intégration d’un autre fournisseur.
• Considérez les exemples de requête comme des indications, mais vérifiez qu’ils correspondent à la même version et à la même opération.

Multipart/form-data et Base64 dans JSON

Avec multipart/form-data, le corps est divisé en parties distinctes. Chaque partie possède ses propres en-têtes et son propre contenu, ce qui permet à une requête de combiner le fichier avec des champs supplémentaires, si l’endpoint les accepte. Le client construit la séparation entre les parties ; c’est pourquoi, avec une bibliothèque HTTP, il est généralement préférable de la laisser générer l’en-tête Content-Type complet et son délimiteur. Définir cet en-tête manuellement sans conserver le délimiteur correspondant au corps est une cause fréquente de requêtes que le serveur ne peut pas analyser.

Avec Base64, les octets du fichier sont convertis en texte, puis ce texte est intégré à un document JSON, par exemple dans une propriété définie par le contrat. Cet encodage augmente généralement la taille transmise par rapport au fichier binaire et ajoute une étape de conversion lors de la préparation et du traitement du contenu. Ne présumez pas du nom de la propriété, de l’exigence d’un préfixe de type de média ni de l’acceptation de Base64 par l’endpoint : ces éléments sont définis par le schéma. Pour les transferts volumineux, comparez les coûts et les limites documentées avant de choisir.

• Multipart convient lorsque le contrat décrit des parties de formulaire et une partie de fichier.
• Base64 n’est une option que si l’endpoint déclare cette représentation ; le fait que le corps soit en JSON ne suffit pas.

Examiner OpenAPI sans faire de suppositions

Consultez la spécification OpenAPI disponible et repérez l’opération exacte à partir de la route et de la méthode. Vérifiez le type de contenu accepté par le corps de la requête, le schéma associé et les propriétés obligatoires. Pour multipart, vérifiez la déclaration du fichier et les noms des parties ; pour JSON, recherchez la structure et le type de données indiqués pour chaque champ. La documentation OpenAPI est importante, car l’acceptation des transferts multipart doit être définie dans le contrat plutôt que déduite intuitivement.

Consultez également les réponses documentées, les exigences d’authentification ainsi que toute limite ou restriction associée à l’opération. Un exemple ne décrit pas nécessairement tous les cas valides, et l’absence d’information ne signifie pas que l’envoi de fichiers arbitraires est autorisé. Si le schéma manque, si le type de contenu n’est pas clair ou si les instructions se contredisent, demandez confirmation au responsable de l’API avant de coder. Notez la version du contrat utilisée pour l’implémentation et les tests.

• Vérifiez la méthode, la route, le Content-Type, le schéma du corps, les champs obligatoires et les réponses possibles.
• Ne déduisez pas les limites, les autorisations, les formats acceptés ou le stockage à partir d’une description générale du produit.

Construire la requête et éviter les erreurs courantes

Dans un exemple conceptuel multipart, le client envoie une partie portant le nom de champ déclaré par le contrat et contenant les données binaires du fichier ; il ne peut inclure d’autres parties que si elles sont documentées. Dans un exemple conceptuel JSON, lisez les octets, encodez-les en Base64 et placez-les dans la propriété exacte définie par le schéma. Ces exemples décrivent des modèles, pas une requête compatible avec un endpoint précis d’Apification. L’intégration d’Apification comprend REST API et OpenAPI, mais les informations disponibles ici ne précisent pas quelle opération accepte des fichiers ni quel schéma elle utilise.

Vérifiez que le fichier s’ouvre correctement avant l’envoi et que le programme ne lit pas un mauvais chemin, un fichier vide ou une version partielle. Ne confondez pas le nom ou l’extension avec le type MIME : ils peuvent ne pas correspondre, et la valeur à transmettre dépend du contrat. Évitez de tronquer le contenu Base64 lors de la journalisation des requêtes ou du transfert de JSON entre composants. Contrôlez également les limites de taille côté client, intermédiaires et serveur, car un rejet peut intervenir avant que l’endpoint ne traite le corps.

• Erreurs fréquentes : nom de champ incorrect, JSON mal formé, délimiteur multipart manquant, contenu Base64 tronqué et type MIME non accepté.
• Ne consignez pas le contenu complet du fichier dans les journaux ; enregistrez les métadonnées nécessaires au diagnostic sans exposer le document.

Vérifier de bout en bout que le fichier n’a pas été corrompu

Une réponse HTTP réussie ne prouve pas à elle seule que le contenu stocké correspond au fichier d’origine. Concevez un test qui envoie un fichier représentatif, puis récupère l’objet reçu à l’aide du mécanisme documenté par l’API. Si aucune méthode de récupération n’est documentée, confirmez quelle vérification le service propose ; ne supposez ni que la réponse contient le fichier ni qu’une opération de téléchargement existe. Conservez l’original de test sans le modifier et notez sa taille et, si le processus le permet, une empreinte calculée localement.

Comparez le fichier récupéré à l’original par comparaison binaire ou en calculant la même empreinte pour les deux. Effectuez des tests avec plusieurs types et tailles adaptés à l’intégration, notamment des fichiers petits et des fichiers proches de la limite documentée. Vérifiez également le code de réponse, le corps de l’erreur et les journaux sécurisés du client. Si le résultat diffère, isolez l’étape où le changement s’est produit : lecture locale, encodage, transport, traitement par le serveur ou téléchargement ultérieur.

• Testez au moins un fichier binaire et un fichier contenant du texte ; incluez des noms comportant des espaces ou des caractères non ASCII si le contrat le permet.
• Répétez le test avec des requêtes dépassant les limites uniquement dans un environnement contrôlé et vérifiez que le rejet est explicite et ne laisse pas d’objet partiel.

Liste de contrôle avant l’intégration

Avant le déploiement, transformez le contrat en une liste vérifiable : opération et version correctes, type de contenu déclaré, champs et noms exacts, authentification requise, limites connues et manière d’interpréter les réponses. Construisez la requête avec une bibliothèque qui gère correctement multipart ou avec une sérialisation JSON fiable. Définissez la conduite à tenir en cas d’erreur réseau, de rejet lié à la taille, d’identifiants invalides ou de réponse mal formée. Réessayer automatiquement un transfert n’est pas toujours sans conséquence : déterminez si l’endpoint autorise sa répétition sans créer de doublons ou de résultats ambigus.

Complétez la vérification par des contrôles opérationnels. Limitez l’accès au fichier source selon les besoins de l’intégration, évitez d’inclure des identifiants ou du contenu sensible dans les journaux et supprimez les fichiers temporaires lorsqu’ils ne sont plus nécessaires. Documentez la procédure permettant de reproduire un transfert échoué à l’aide d’un fichier de test et de valider sa réception. Apification propose l’intégration de Cloud et de ses services au moyen de REST API, OpenAPI, webhooks, iframe et JavaScript ; les détails des transferts, des autorisations et des capacités de chaque endpoint doivent être confirmés dans la documentation applicable et ne doivent pas être déduits de cette capacité générale.

• Contrat vérifié et versionné.
• Représentation et limites confirmées pour l’endpoint concerné.
• Tests d’intégrité, de gestion des erreurs et de nouvelles tentatives effectués.
• Accès, journaux et fichiers temporaires vérifiés.

Questions fréquentes