Qu'est-ce que le payload dans une interaction API

Lorsqu’un client et un serveur communiquent via API, le premier envoie une requête au second, qui traite la requête et renvoie une charge utile contenant le résultat de l’opération, qui peut concerner la création d’un nouvel utilisateur autant que l’extraction d’informations depuis une base de données.

La charge utile, ou «payload» de l’interaction, est cette partie de la communication qui contient les données à transmettre, par exemple le nom d’utilisateur et l’adresse e-mail à associer à un nouveau compte ou le résumé de l’opération effectuée.

Payload: ce que c’est et ce qu’il contient

Lors de la transmission de données, le payload est la portion du message qui contient les données à transmettre, littéralement la « charge utile » de l’échange d’informations entre client et serveur.

Lorsque le client envoie une requête, il transmet un paquet de données qui inclut plusieurs instructions nécessaires au fonctionnement du protocole de communication, comme les métadonnées et les en-têtes, qui transportent des informations telles que le type de contenu ou d’éventuels messages d’erreur. Le payload se trouve à l’intérieur du même paquet et contient les données réelles à transmettre.

Dans une requête, par exemple, le payload peut contenir les données d’un utilisateur qui se connecte ou la requête dans un appel API, tandis que dans une réponse, il peut contenir le résultat de l’opération ou les données demandées.

Le contenu du payload dépend essentiellement du contexte: dans le traitement des paiements, il peut inclure des identifiants, des détails de paiement et des métadonnées liées à la transaction; sur les réseaux sociaux, il peut transmettre des fichiers multimédias ; dans les systèmes de réservation, il peut transporter des informations comme les disponibilités et les tarifs.

Le Payload dans les requêtes API: quelques exemples

Le payload est donc le message réellement transmis entre le client et le serveur. Il peut s’agir d’une image, d’un PDF ou d’une liste de noms. Dans les interactions impliquant la transmission de métadonnées, il s’agit presque toujours d’un objet au format Json ou XML, dont le contenu peut varier considérablement selon le type d’opération.

Par exemple, si nous créons un nouvel utilisateur, le payload de la requête doit contenir les données nécessaires à la création du compte (ex. : {"username": "nouvelutilisateur", "email": "[email protected]", "firstName": "Mario", "lastName": "Rossi"}), tandis que la réponse inclura des informations comme l’ID du nouvel utilisateur, ses données et un message du type « Compte créé avec succès » (ex. : {"id": "123", "username": "nouvelutilisateur", "email": "[email protected]", "message": "Compte créé avec succès"}).

Si nous récupérons des informations à partir d’une base de données, le payload de la requête correspondra à la requête spécifique (par exemple, {"query": {vatCode_or_taxCode_or_id}}), tandis que la réponse contiendra les données demandées, dans notre cas {"taxCode": "12485671007", "companyName": "OPENAPI SPA", "vatCode": "12485671007"}.

Le payload dans les Rest API : les méthodes HTTP

Dans les appels Rest API, le contenu du payload dépend également beaucoup de la méthode HTTP utilisée, qui définit l’action à effectuer sur la ressource sollicitée:

• GET: méthode utilisée pour lire des données depuis un serveur, par exemple extraire des données d’une base de données. Dans les requêtes GET, le payload contient les données demandées (voir exemple ci-dessus). Il est utilisé uniquement dans la réponse, car les données nécessaires à la requête sont généralement déjà incluses dans la chaîne ou l’objet request;
• POST: si vous créez une nouvelle ressource sur le serveur, par exemple ajouter un nouveau produit dans un e-commerce, le payload de la requête doit contenir les données nécessaires à la création de la ressource, et sera un Json du type {"name": "Nom produit", "price": 123, "description": "Description produit.", "category": "Catégorie produit"}. La réponse contiendra le résultat de la requête, c’est-à-dire le statut de succès et les détails de la création de la nouvelle ressource, par exemple l’ID et la date de création;
• PUT: lors de la mise à jour de ressources, le payload doit contenir une représentation complète de la ressource à mettre à jour, y compris les nouvelles valeurs à définir. Pour les produits d’un e-commerce, par exemple, le payload de la requête PUT contiendra des informations du type {"id": "123", "name": "Nouveau Nom Produit", "price": "Nouveau prix", "available": true}. Le payload de la réponse contient généralement un statut de succès et un message du type «produit mis à jour avec succès»;
• DELETE: une requête DELETE ne nécessite pas de payload mais peut inclure des informations telles que l’ID de la ressource à supprimer ou d’autres détails. La réponse contient presque toujours uniquement le statut de succès et éventuellement quelques détails sur l’opération;
• PATCH: dans les requêtes PATCH, le payload contient uniquement les données à modifier. Par exemple, si nous voulons mettre à jour le champ e-mail de l’utilisateur avec ID 123, le payload envoyé à l’endpoint correspondant contiendra uniquement la nouvelle adresse e-mail, tandis que la réponse peut renvoyer les éléments modifiés ou la ressource complète mise à jour, avec le statut de succès.

Le payload dans les interactions avec l’API Openapi

Les payloads transmis dans une interaction API, en particulier les payloads de réponse, contiennent beaucoup plus que les seules données demandées. Ils incluent des informations essentielles pour la gestion de l’interaction par le client, telles que le statut de succès (par exemple, “success”: true) et d’éventuels messages textuels (par exemple, “message”: “mot de passe invalide”).

Les payloads de l’API Openapi utilisent le standard Json. Dans les requêtes API, ils contiennent les informations de la requête, par exemple l’expéditeur, le destinataire et le contenu d’un SMS.

Dans les réponses API Openapi, les payloads contiennent 4 champs:

• Data: les données transmises. Dans une requête pour l’envoi d’une lettre recommandée via API, par exemple, la section “data” inclut toutes les informations nécessaires à l’envoi, comme les informations de l’expéditeur, le nom et l’adresse du destinataire, le message à envoyer et les options d’impression. Dans la réponse, les mêmes données seront présentes, ainsi que l’URL du document et les détails du paiement;
• Success: indique le statut de succès, peut être "success": true ou "success": false;
• Error: communique les éventuels messages d’erreur;
• Message: section du payload qui inclut les messages destinés aux utilisateurs finaux, souvent envoyés en cas d’erreur ou de données manquantes dans la requête, par exemple "requête invalide" ou "préciser le type de paiement".

Le payload, comme nous l’avons vu, est le contrat fondamental entre client et serveur, l’élément qui définit l’intention (request) et le résultat (response) de l’interaction. Par conséquent, sa structure peut influencer fortement l’efficacité et l’évolutivité d’une architecture API. Une structure stricte et cohérente des payloads est donc indispensable pour garantir l’interopérabilité et la facilité d’intégration, mais aussi pour assurer des processus efficaces et facilement maintenables.