Cos'è il payload in un’interazione API?

Quando un client e un server comunicano tramite API, il primo invia una richiesta al secondo, che elabora la richiesta e restituisce un payload contenente il risultato dell'operazione, che può riguardare la creazione di un nuovo utente tanto quanto l’estrazione di informazioni da un database.

Il payload, o “carico utile” dell’interazione, è quella parte della comunicazione che contiene i dati da trasmettere, per esempio il nome utente e l’indirizzo email da associare a un nuovo account o il riepilogo dell’operazione effettuata.

Payload: cos’è e cosa contiene

Nella trasmissione di dati, il payload è la porzione di messaggio che contiene i dati da trasmettere, letteralmente il “carico utile” dello scambio di informazioni tra client e server.

Quando un client invia una richiesta, trasmette un pacchetto di dati che include diverse istruzioni necessarie a far funzionare il protocollo di comunicazione, come metadati e header, che trasportano informazioni come il tipo di contenuto o eventuali messaggi di errore. Il payload si trova all’interno dello stesso pacchetto, ed è quello che contiene i dati effettivi da trasmettere.

In una richiesta, per esempio, il payload può contenere i dati di un utente che effettua il login oppure la query in una chiamata API, mentre in una risposta può contenere il risultato dell’operazione o i dati richiesti.

Il contenuto del payload dipende essenzialmente dal contesto: nell’elaborazione dei pagamenti può includere credenziali, dettagli di pagamento e metadati relativi alla transazione, nei social network può trasmettere file multimediali, nei sistemi di prenotazione può trasportare informazioni come disponibilità e prezzi.

Il Payload nelle chiamate API: qualche esempio

Il payload, quindi, è il messaggio che viene effettivamente trasmesso tra client e server. Può essere un’immagine, un PDF o una lista di nomi. Nelle interazioni che prevedono la trasmissione di metadati, si tratta quasi sempre di un oggetto in formato Json o XML, il cui contenuto può variare notevolmente in base al tipo di operazione. 

Se per esempio stiamo creando un nuovo utente, il payload di richiesta dovrà contenere i dati necessari alla creazione del nuovo account (es.: {"username": "nuovoutente", "email": “[email protected]", "firstName": "Mario", "lastName": "Rossi"}), mentre quello della risposta includerà informazioni come l’ID del nuovo utente, i suoi dati e un messaggio del tipo “Account creato con successo" (es.: {"id": "123", "username": "nuovoutente", "email": "[email protected]", "message": "Account creato con successo"}).

Se stiamo invece recuperando informazioni da un database, il payload della richiesta coinciderà con la query specifica (per esempio, {"query": {vatCode_or_taxCode_or_id}), mentre la risposta conterrà i dati richiesti, nel nostro caso {"taxCode": "12485671007",  "companyName": OPENAPI SPA", "vatCode": "12485671007"}.

Il payload nelle Rest API: i metodi HTTP

Nelle chiamate API Rest, il contenuto del payload dipende molto anche dal metodo HTTP utilizzato, che definisce l’azione da eseguire sulla risorsa interpellata:

• GET: è il metodo usato per leggere dati da un server, per esempio estrarre dati da un database. Nelle richieste GET, il payload contiene i dati richiesti (vedi esempio sopra). Si usa soltanto nella risposta, poiché i dati necessari alla richiesta sono generalmente già inseriti nella stringa o nell’oggetto request;
• POST: se si sta creando una nuova risorsa sul server, per esempio si sta inserendo un nuovo prodotto in un e-commerce, il payload di richiesta deve contenere i dati necessari alla creazione della nuova risorsa, e sarà un Json del tipo {"nome": "Nome prodotto", "prezzo": 123, "descrizione": "Descrizione prodotto.", "categoria": "Categoria prodotto"}.   La risposta conterrà l’esito della richiesta, cioè lo stato di successo e i dettagli sulla creazione del nuovo prodotto, per esempio l’ID e la data di creazione della risorsa
• PUT: nell’aggiornamento delle risorse, il payload deve contenere una rappresentazione completa della risorsa da aggiornare, comprensiva dei nuovi valori da impostare. Nell’aggiornamento dei prodotti di un e-commerce, per esempio, il payload della richiesta PUT conterrà informazioni del tipo {"id": "123", "nome": "Nuovo Nome Prodotto", "prezzo": “Nuovo prezzo”, "disponibile": true}. Il payload della risposta, invece, contiene generalmente uno stato di successo e una risposta del tipo “prodotto aggiornato con successo”.
• DELETE: una richiesta DELETE non necessita di payload, ma può includere informazioni come l’ID della risorsa da eliminare o altri dettagli. La risposta invece contiene quasi sempre solo lo stato di successo ed eventualmente qualche dettaglio sull’operazione;
• PATCH: nelle richieste PATCH, il payload contiene solo i dati da modificare. Se per esempio vogliamo aggiornare un campo email del solito utente con ID 123, il payload inviato all’endpoint che identifica l'utente da modificare conterrà solo il nuovo indirizzo email, mentre la risposta può restituire gli elementi modificati oppure l’intera risorsa aggiornata, insieme allo stato di successo.

Il payload nelle interazioni con le API di Openapi

I payload trasmessi in un’interazione via API, soprattutto quelli delle risposte (API Responses), contengono molto di più dei semplici dati richiesti. Includono informazioni essenziali per la gestione dell'interazione da parte del client, come lo stato di successo (per esempio, “success”: true) ed eventuali messaggi testuali (per esempio, “message”: “password non valida”).

I payload delle API di Openapi adottano lo standard Json. Nelle richieste API, contengono l’informazione della richiesta, per esempio mittente, destinatario e contenuto di un SMS. 

Nelle API responses di OpenAPI, invece, i payload contengono 4 campi:

• Data, ovvero i dati trasmessi. In una richiesta per l’invio di una raccomandata via API, per esempio, la sezione “data” include tutte le informazioni necessarie all’invio, come i dati del mittente, nome e indirizzo del destinatario, il messaggio da inviare e le opzioni di stampa. Nella risposta si troveranno gli stessi dati, ma anche l’URL del documento e i dettagli del pagamento;
• Success: indica lo stato di successo, può essere "success": true oppure "success": false;
• Error: comunica eventuali messaggi di errore;
• Message: è la sezione del payload che include eventuali messaggi destinati agli utenti finali, spesso inviati in corrispondenza di un errore o di dati mancanti nella richiesta, per esempio "query non valida” o “specificare il tipo di pagamento”.

Il payload, abbiamo visto, è il contratto fondamentale tra client e server, l'elemento che definisce l'intento (request) e il risultato (response) dell’interazione. Perciò la sua struttura può influenzare notevolmente l’efficienza e la scalabilità di un’architettura API. Una struttura rigorosa e coerente dei payload è quindi indispensabile per garantire interoperabilità e facilità di integrazione, ma anche per assicurare processi efficienti e di facile manutenzione.