API: SOAP vs REST
Quando un’azienda ha un software, ha tra le mani una grande risorsa: un programma progettato per rispondere ad un’esigenza specifica, e diresti che la soddisfa. Questo software magari processa dati, e forse anche numerosi; oppure elabora degli input in maniera originale, fornisce informazioni, ti aiuta a gestire uno spazio, il tuo lavoro, il lavoro di altre persone. Tutto questo succede grazie al tuo programma, che in questo momento sta eseguendo incessantemente, quasi non lo diresti se non fosse per il ronzio proveniente dal computer.
Tutte queste operazioni, tutti questi dati sono molto utili alla tua azienda. Un giorno si presenta da te un cliente che ha bisogno di fare le stesse operazioni, che ha bisogno di leggere i dati gestiti dal tuo software. Ma è tutto in quel computer! E hai bisogno che il cliente faccia sì delle operazioni, ma in maniera prevedibile, sicura, e che non sia in grado di fare più del necessario. Quando si tratta di fargli leggere i tuoi dati, è come se volessi dargli una chiave che apre una finestrella: guarda quello che gli serve ma, non può toccare nulla.
Ci sono tanti modi per fare questa cosa: potresti copiare alcune tabelle del DB, così può consultarle con calma, ma non sarebbero aggiornate. Potresti mettere tutto online e dare accesso al database, ma significherebbe conferire molte responsabilità su quei dati anche sul tuo cliente. Il metodo che vogliamo suggerirvi in questo articolo è quello delle API.
API sta per Application Programming Interface. Si tratta di un software intermediario che permette a due applicazioni di parlare e compiere operazioni tra di loro. Ne esistono di diversi tipi, ma ci interessano in particolare quelle che permettono delle comunicazioni via web. In questo modo possiamo concentrarci su quelle infrastrutture che ci permettono di compiere operazioni tra sistemi in una rete; garanendo al cliente l’accesso al software e alla tua azienda la sicurezza dei dati.
Col tempo sono andati definendosi diversi paradigmi: ad esempio SOAP, REST o GraphQL. In questo articolo ti parlerò dei primi due.
Entrambi i paradigmi nascono in un periodo in cui diverse fondazioni che si occupano ancora oggi di standard su Internet stavano cercando di stabilire dei modi condivisi di comunicare su Internet. I siti internet di uso generale iniziavano ad essere diffusi in tutto il mondo e l’architettura web non aveva ancora fissato dei protocolli di comunicazione precisi, diffusi, condivisi.
SOAP muove i primi passi alla fine degli anni 90, diventa una raccomandazione W3C nel 2003. È un protocollo di comunicazione, molto solido ma anche molto rigido e verboso. Nel 2000 SalesForce vende come servizio ai suoi clienti l’utilizzo di una API SOAP.
REST è uno stile architetturale di definizione delle API web che Roy Fielding ha presentato per la prima volta nella sua tesi di dottorato nel 2000. Ci sono tanti servizi che ne fanno subito uso, ad esempio Flickr che nel 2004 ha messo a disposizione la sua prima API RESTful pubblica, per potenziare la diffusione dei suoi contenuti sul web e consentire a qualsiasi blog o sito internet di postare foto da Flickr e interagire con i loro servizi.
</p> <pre><?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header /> <SOAP-ENV:Body> <ns3:GetDistrictByAddressResponse xmlns:ns3="http://il/co/bar/webservices/getdistrictbyaddress"> <TimeFrameTable> <CustomerNumber>250</CustomerNumber> <Row> <WindowDate>10052016</WindowDate> <WeekDay>Sunday</WeekDay> <FromHour>1130</FromHour> <ToHour>1430</ToHour> </Row> <Row> <WindowDate>10052016</WindowDate> <WeekDay>Sunday</WeekDay> <FromHour>1430</FromHour> <ToHour>1730</ToHour> </Row> </TimeFrameTable> </ns3:GetDistrictByAddressResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope></pre> <p>
Ecco la stessa richiesta fatta con REST
</p>
<pre>{
dates: [
{windowDate: 10052016, weekDay:”Sunday”, from:1130, to:1430},
{windowDate: 10052016, weekDay:”Sunday”, from:1430, to:1730}
]
}</pre>
<p>
Possiamo osservare subito come la richiesta SOAP sia più lunga, e utilizzi per il corpo della richiesta il formato XML. La richiesta REST, più breve, utilizza il formato JSON, un po’ più snello.
Per fare un esempio, questo elemento XML della chiamata SOAP
</p> <pre><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> … </SOAP-ENV:Envelope></pre> <p>
è così caratterizzato:
- Un tag d’apertura e uno di chiusura <> e </>. Delimitano i confini dell’elemento.
- Un contenuto dell’elemento … che nell’esempio di sopra era composto da altri elementi quali Body, GetDristrictByAddressResponse, etc.
- Un nome dell’elemento, Envelope. Questo nome ci suggerisce quale sia il compito di questo elemento, in questo caso è la “busta” del messaggio che stiamo inviando
- Un namespace, SOAP-ENV. Questo definisce tutti i possibili elementi che possono esistere in un certo namespace, e permette la validazione della richiesta. Nel nostro esempio, possiamo usare Envelope e Body perché sono definiti nel namespace SOAP-ENV
- Un indirizzo di definizione del namespace, http://schemas.xmlsoap.org/soap/envelope/. Questo indirizzo contiene la definizione del namespace appena citato. Qui vengono elencati gli elementi possibili.
Tutte queste caratteristiche si ripetono in maniera simile in tutti gli altri elementi della richiesta XML. Si può notare come questa ripetitività da un lato garantisca la solidità della richiesta: ogni elemento fa parte di un certo namespace, questo namespace è dichiarato e nominato in ogni elemento. C’è una certa libertà nel creare gruppi: con un elemento vuoto come <row> è possibile aggregare un certo numero di contenuti in maniera arbitraria. Occorre essere molto precisi nella scrittura dell’XML altrimenti la richiesta rischia di fallire.
La richiesta REST può essere più semplice. Sebbene nei principi REST non venga indicato quale formato utilizzare per le richieste, è ormai una convenzione comune utilizzare JSON: si tratta di un formato facilmente leggibile sia dagli umani che dalla macchina, e come si vede, non è necessario dichiarare namespace. È buona norma nominare gli oggetti, per sapere cosa significa ogni attributo. Per il resto c’è una grande libertà di utilizzo, e la richiesta risulta particolarmente semplificata. Da notare inoltre, in questo esempio, che manca l’indicazione dell’ID dell’utente, che in SOAP era registrato nell’elemento <CustomerNumber>250</CustomerNumber> . Questo perché possiamo pensare che la chiamata REST avvenga su di un endpoint (un punto di comunicazione dell’API) fatto così:
</p> <pre><a href="http://www.foo.com/" target="_blank" rel="noopener">www.foo.com </a> /customer /250 [dominio del sito web] /nome-risorsa /id-della-risorsa</pre> <p>
Un altro punto da osservare tra le differenze di SOAP e REST sono proprio gli endpoint, e il modo in cui vengono forniti.
Nel protocollo SOAP esiste un elemento non obbligatorio ma fortemente raccomandato e molto utile, direi il punto di forza dell’intero protocollo: il WSDL. WSDL sta per Web Services Description Language, ed è un documento XML che descrive i servizi web disponibili. Sono riportati gli endpoint delle richieste, la forma che devono avere le richieste e cosa aspettarsi dall’output di servizio. Un’applicazione che si interfaccia per la prima volta con un’API SOAP può richiedere il WSDL, se disponibile, e configurare le proprie richieste a quel servizio secondo quanto riportato nel WSDL.
Per quanto riguarda le applicazioni REST invece, si nota una mancanza di questa raccomandazione: non esiste un vero e proprio WSDL per le API REST. Far conoscere ai consumatori della propria API gli endpoint, gli input attesi e gli output del servizio sta agli sviluppatori. L’API va documentata, listati gli endpoint, dati esempi di input e output. Per fortuna esistono delle librerie che permettono di fare questo abbastanza agilmente, e in alcuni framework permette persino di generare la documentazione a partire dal codice che governa l’API. Scrivere la documentazione diventa un compito non più complicato di scrivere il WSDL per un’API SOAP.
Altre caratteristiche importanti da segnalare per SOAP:
- SOAP prevede anche altri moduli da integrare, ad esempio moduli per la sicurezza.
- Gestisce automaticamenti gli errori con l’elemento SOAP-Fault.
- È estendibile e le estensioni seguono a loro volta degli standard.
Altre caratteristiche importanti da segnalare per REST:
- REST ha un ricco ecosistema di librerie.
- Il contenuto dei messaggi è decisamente più leggero e costa meno sulla banda.
- Ha un design vicino ad altre tecnologie Web che lo rendono più semplice da implementare.
Ad oggi SOAP è ancora diffuso per via di sistemi legacy che continuano ad utilizzarlo. Questo può essere funzionale se ormai la rete di consumatori dell’API è stabile e non si vogliono introdurre grandi cambiamenti. Se invece la propria API SOAP viene considerata difficile da utilizzare, non è pronta da essere messa al pubblico, vede un calo degli utenti, si può pensare di fare una migrazione verso REST. È possibile sia convertire l’intero sistema, sia creare un servizio ulteriore che “mascheri” l’API SOAP con una API REST più leggera. Questo potrebbe migliorare l’usabilità del tuo software e la sua diffusione.
Per concludere, SOAP e REST offrono vantaggi differenti, uno è più standardizzato e rigido, l’altro più flessibile e semplice da utilizzare. I vantaggi di utilizzare REST quando si scrive una nuova applicazione sono numerosi, e può convenire utilizzarlo anche per sostituire una vecchia interfaccia SOAP.
In ogni caso i due metodi rimangono validi, e ogni progetto ha le proprie esigenze.
Vuoi scoprire come valorizzare il tuo software creando un’API?
