Facciamo chiarezza su REST e le RESTful API

Nel mio lavoro mi capita molto spesso di formare nuovi sviluppatori che desiderano creare la prossima grande applicazione che verrà utilizzata dal mondo intero.

Alcuni mirano a creare un nuovo Facebook, altri a creare il nuovo Airbnb mentre altri ancora hanno in mente qualcosa di totalmente diverso.

Dato che sono diversi anni che seguo questo campo, anche dal punto di vista del marketing, molto spesso mi trovo a chiedere ai miei studenti:

“Come pensi di scalare la tua applicazione?”

Quella che ritengo una semplice domanda ottiene spesso le risposte più varie.

Alcuni mi rispondono con profonde analisi su come andranno a scalare l’architettura dell’infrastruttura hardware, altri hanno già valutato l’utilizzo di un diverso linguaggio di programmazione mentre altri ancora mi parlano della brillante idea di assumere freelancer indiani (per il loro basso costo) che li aiuteranno a incrementare le funzionalità offerte dall’applicazione stessa.

Il problema che mi trovo ad affrontare è che non sono queste le risposte che mi aspetto, piuttosto quello che avrei voluto sentire è come consentire ad altri sviluppatori di accedere alle informazioni contenute all’interno della propria applicazione e magari anche di crearne di nuove.

Probabilmente quanto appena detto ha spiazzato anche te, ma se stiamo costruendo qualcosa per le masse dobbiamo anche garantirci un metodo per raggiungerle nel modo più semplice possibile.

Questo perché Facebook, Twitter, GitHub e lo stesso Unsplash non sarebbero arrivati a coprire l’importanza sul mercato che hanno oggi se non avessero messo a disposizione un set di API.

Ma non dovevamo parlare di REST?

Ti faccio i miei complimenti, nonostante la mia introduzione ti ricordi ancora il titolo di questo articolo e magari è proprio il motivo per il quale stai ancora leggendo.

Non ti preoccupare, a breve andremo ad approfondire il significato e gli usi di questo acronimo ma ho avuto la necessità di introdurti prima i concetti relativi alle API per farti capire nel complesso come sia possibile sfruttare queste caratteristiche all’interno della tua prossima applicazione.

Dalla frase precedente forse ti sei chiesto perché mettere a disposizione le informazioni collezionate dalla tua applicazione anche ad altri sviluppatori.

Se utilizzi una widget Facebook, Twitter o anche Pinterest all’interno del tuo sito web la risposta dovrebbe essere ovvia: perché fornendo queste informazioni potrai raggiungere un’audience maggiore rappresentata da tutti i siti web che vogliono mostrare il contenuto raccolto dalla tua app.

Anche se essenziale alla crescita di qualsiasi applicazione mettiamo per un momento da parte il marketing.

Sviluppare un set di API è un ottimo esercizio di sviluppo. Lo vediamo da diversi anni ormai e adesso che anche WordPress offre le sue API possiamo iniziare a sviluppare più facilmente.

Con l’acronimo API si intende Application Programming Interface e non è altro che la creazione di una serie di endpoint (delle URL) che rispondono alle richieste fatte da uno sviluppatore.

Praticamente una raccolta di metodi che ci permettono di collegare librerie o applicazioni presenti su diversi sistemi.

Il significato di REST e RESTful API

Se non ti ho ancora perso ma anzi ti sei ulteriormente incuriosito, non posso fare altro che premiarti dicendoti che il significato dell’acronimo REST è REpresentational State Transfer, ovvero una rappresentazione del trasferimento di stato di un determinato dato.

Comprendo che probabilmente la spiegazione non è stata di tuo gradimento ma ti confesso che c’è veramente ben poco altro da capire a riguardo.

Questo perché REST non è una tecnologia, piuttosto descrive una serie di linee guida e di approcci che definiscono lo stile con cui i dati vengono trasmessi.

Dato l’interesse sulla trasmissione di dati questa tecnica viene spesso utilizzata per la creazione di applicazioni web ma spero che non ti stupisca troppo che lo stesso Windows ha una serie di API che permettono alle proprie applicazioni di comunicare tra loro.

Nel web moderno ormai REST e API sono termini che si usano quasi indistintamente, ma non dimenticarti che non sono la stessa cosa, tantomeno dei sinonimi!

Da bravo sviluppatore quello che potrai fare è creare un set di API che rispettano la logica imposta da REST creando un set di RESTful API.

È possibile definire un’architettura standard per le REST?

Rispondo immediatamente a questa domanda in modo secco: non è possibile definire uno standard perché l’approccio sulla loro costruzione può variare da sviluppatore a sviluppatore.

Quello che però è possibile fare è tracciare alcuni punti che generalmente sono presenti all’interno di qualsiasi applicazione di questo tipo:

• c’è una consistenza all’interno dell’intera API;
• lo sviluppo di questa soluzione non implica la creazione di sessioni all’interno dei nostri server creando quindi un’esistenza stateless dove il nostro server, tra un’operazione e un’altra, non salva le informazioni di login;
• quando appropriato vengono utilizzati gli status code HTTP che aiutano e velocizzano le risposte dei nostri server;
• vengono create delle URL endpoint che seguono una determinata logica;
• la versione delle API viene salvata nelle URL piuttosto che all’interno degli status code HTTP.

Come ti ho già avvisato non possiamo considerare queste regole come dei comandamenti che lo sviluppatore segue durante lo sviluppo o l’utilizzo di RESTful API ma dato che sono presenti all’interno di moltissime soluzioni già implementate possiamo aspettarci di trovarne alcune (se non tutte) all’interno delle API rilasciate da alcuni servizi.

Sono convinto che tutte queste informazioni teoriche ti stanno facendo girare la testa, quindi perché non andiamo ad analizzare qualcosa di più pratico come per esempio le azioni che possiamo svolgere con questa tecnologia?

Se hai già sviluppato qualche applicazione web che fa uso di database forse i prossimi punti ti suoneranno familiari, questo perché anche se stiamo utilizzando delle API stiamo sempre svolgendo delle operazioni all’interno di un database installato su qualche server connesso online:

• GET questo ci permette di richiedere al server un determinato set di dati;
• POST la possibilità di creare un nuovo oggetto all’interno del database;
• PUT con questo possiamo modificare o sostituire completamente un oggetto già esistente;
• DELETE possiamo, da remoto, cancellare un oggetto contenuto all’interno del database al quale siamo collegati.

Praticamente una buona API ci permette di fare tutte queste operazioni senza la necessità di dover accedere direttamente al database o alla soluzione implementata per il salvataggio delle informazioni.

Ogni azione descritta precedentemente deve essere passata a uno specifico endpoint che ci permetterà di ottenere determinate funzionalità.

Ma quando si usano queste soluzioni?

Probabilmente sto mettendo troppa carne al fuoco o forse è soltanto frutto della mia immaginazione ma sento il bisogno di spiegare ulteriormente (e a parole mie) il significato e gli utilizzi di questi acronimi.

Se ti senti confidente e sei sicuro di aver compreso bene i concetti che abbiamo esposto precedentemente, puoi saltare tranquillamente nella sezione successiva di questo articolo.

Continuando a leggere scoprirai ulteriori concetti che ti potranno essere utili nel tuo lavoro.

Iniziamo subito con un esempio.

Hai il tuo sito web su http://tuodominio.it all’interno del quale pubblichi ogni settimana del nuovo contenuto. Il tuo desiderio adesso è quello di inserire nella sidebar di http://altrotuodominio.it una widget in grado di visualizzare gli ultimi 5 articoli pubblicati sul sito precedente.

Immagino tu sappia che esiste una tecnologia chiamata RSS che permette di sviluppare una soluzione in grado di ottenere gli ultimi articoli che sono stati pubblicati su un altro blog, magari aiutato dalla libreria PHP SimplePie.

Con una libreria del genere puoi raggiungere il risultato desiderato ma che succede se decidi di mostrare dal 20esimo al 25esimo articolo presente sul tuo sito di riferimento?

Molto probabilmente la soluzione che ti ho appena indicato non è più utilizzabile perché, a meno di configurazioni specifiche, un feed RSS è in grado di distribuire soltanto gli ultimi 10 articoli apparsi in un blog.

Facciamola anche più difficile…

Come potresti fare se su http://altrotuodominio.it decidi di inserire un motore di ricerca per gli articoli presenti su http://tuodominio.it?

Adesso il problema non può più essere risolto con un semplice feed RSS…

Ebbene per raggiungere questo risultato una delle soluzioni più semplici che potrai mettere in atto è utilizzare delle RESTful API. Con un’installazione WordPress possiamo risolvere i precedenti problemi con le seguenti endpoint URL:

• http://tuodominio.it/wp-json/wp/v2/posts?offset=20&per_page=5 – con questa URL sarai in grado di ottenere in risposta l’oggetto JSON che contiene gli articoli dal 20 al 25;
• http://tuodominio.it/wp-json/wp/v2/posts?search=stringa%20da%20cercare – mentre grazie a questa potrai cercare “stringa da cercare” all’interno del sito esterno.

Ovviamente dovrai inserire su http://altrotuodominio.it il codice PHP o JavaScript in grado di utilizzare i dati dell’oggetto JSON che otterrai in risposta ma tutto il duro lavoro di raccogliere gli articoli adeguati o di eseguire una ricerca sul sito principale vengono svolti dalle API che stiamo utilizzando.

Al posto di sviluppare una soluzione ad hoc che ti consente di connetterti al database principale ed eseguire le query specifiche credo proprio che la soluzione precedente risulti molto più semplice, non lo pensi anche tu?

Come connettersi alle API nel mondo reale

Spero che con le informazioni che ti ho fornito adesso il concetto di RESTful API sia più chiaro, in fin dei conti non è altro che un insieme di tecniche che ci permettono di collegarsi a un server esterno ed eseguire alcune operazioni sui dati che esso contiene.

Per il momento ci siamo impegnati su delle richieste di tipo GET per due motivi principali:

1. sono il tipo di richieste che qualsiasi API è in grado di soddisfare, sempre se programmata per restituire dei dati;
2. sono il tipo di richieste che possiamo fare senza richiedere un’autenticazione, ovviamente a meno che il servizio che stiamo utilizzando non la richieda esplicitamente.

Quindi, anche se precedentemente ti avevo detto che con delle RESTful API non vengono salvate informazioni di login tra un’operazione e un’altra, questo non vuol dire che non possiamo eseguire un login ad ogni operazione.

Questo concetto apre le porte a molti altri aspetti che potremmo trattare in successivi articoli o magari in un corso dedicato ma la cosa importante che ti voglio far capire è che (giustamente) chi crea un set di API non permette a chiunque di scrivere dei dati all’interno della propria applicazione.

A parte la possibilità di permettere agli utenti di inserire del codice malevolo, attraverso azioni di tipo POST, se lasciamo aperte anche le azioni di tipo PUT e DELETE rischiamo di ritrovarci con un database completamente vuoto!

Per questo motivo, a ogni richiesta via API che desidera utilizzare queste azioni, è necessario loggarsi all’interno del sistema che vogliamo utilizzare.

Per fare questo generalmente si usa una tecnologia che prende il nome di oAuth e che permette di creare delle connessioni sicure tra computer andando a salvare un token che è consultabile soltanto dai computer che hanno eseguito questa connessione.

Come dicevo precedentemente, non è mia intenzione entrare nel dettaglio del protocollo oAuth perché per quanto il funzionamento possa sembrare semplice, ci sono molti concetti di sicurezza al suo interno che mi forzeranno a delle spiegazioni approfondite.

Ho desiderato citarlo perché come accade molto spesso doverlo utilizzare ma voglio lasciare l’approfondimento di questo aspetto in un articolo separato.

Sei curioso di scoprire come funziona questa tecnica di autenticazione? Fammelo sapere all’interno dei commenti 😉

Conclusioni

Siamo giunti al termine di questo articolo la mia speranza è che tu possa uscirne soddisfatto e con qualche concetto in più salvo nella tua mente.

In fin dei conti quando si parla di RESTful API e di REST in generale le informazioni base che si possono offrire non sono poi molte perché a parte alcuni concetti standard, come per esempio le operazioni che possono essere svolte attraverso questa tecnologia, tutto il resto si affida a come il servizio ha strutturato il suo servizio.

Come hai visto, WordPress ha creato delle API molto semplici dove basta utilizzare la corretta URL per ottenere in GET le informazioni che stiamo cercando, ma non sempre è così e bisogna leggere le documentazioni dei singoli servizi.

Leggendo per esempio quella delle API di Unsplash si scopre che questo servizio non risponde alle proprie URL restituendo un oggetto JSON ma fornendoci il link all’immagine che stiamo cercando.

Ora sto forse divulgando troppo e non sto trattando il servizio che a te interessa, ma ti assicuro che una volta che avrai compreso come sia semplice includere le REST nel tuo sviluppo sarai in grado di fare moltissime altre cose senza dover creare necessariamente l’infrastruttura che sta alla base.

Non esitare a farmi sapere che cosa ne pensi e se hai beneficiato dalla lettura di questo articolo. Soprattutto fammi capire se sei interessato a questo argomento, mi fa sempre piacere leggere i tuoi commenti e trarre nuovi spunti per creare nuovi articoli e corsi!