Comprensione e utilizzo delle API REST

C'è un'alta probabilità che ti sia imbattuto nel termine "API REST" se hai pensato di ottenere dati da un'altra fonte su Internet, come Twitter o Github. Ma cos'è un'API REST? Cosa posso fare per Te? Come lo usi?

In questo articolo imparerai tutto ciò che devi sapere sulle API REST per poter leggere la documentazione delle API e usarle in modo efficace.

Che cos'è un'API REST

Diciamo che stai cercando di trovare video su Batman su Youtube. Apri Youtube, digita "Batman" in un campo di ricerca, premi invio e vedrai un elenco di video su Batman. Un'API REST funziona in modo simile. Cerchi qualcosa e ottieni un elenco di risultati dal servizio da cui stai richiedendo.

Un'API è un'interfaccia di programmazione dell'applicazione. È un insieme di regole che consentono ai programmi di dialogare tra loro. Lo sviluppatore crea l'API sul server e consente al client di parlare con esso.

REST determina l'aspetto dell'API. Sta per "trasferimento di stato rappresentativo". È un insieme di regole che gli sviluppatori seguono quando creano la loro API. Una di queste regole afferma che dovresti essere in grado di ottenere un dato (chiamato risorsa) quando ti colleghi a un URL specifico.

Ogni URL è chiamato richiesta , mentre i dati inviati all'utente sono chiamati risposta .

L'anatomia di una richiesta

È importante sapere che una richiesta è composta da quattro cose:

1. Il punto finale
2. Il metodo
3. Le intestazioni
4. I dati (o il corpo)

L'endpoint (o percorso) è l'URL richiesto. Segue questa struttura:

 root-endpoint/ ? root-endpoint/ ? root-endpoint/ ?

L' endpoint radice è il punto di partenza dell'API da cui stai richiedendo. L'endpoint radice dell'API di Github è https://api.github.com mentre l'API di Twitter dell'endpoint radice è https://api.twitter.com .

Il percorso determina la risorsa che stai richiedendo. Pensala come una segreteria telefonica automatica che ti chiede di premere 1 per un servizio, premere 2 per un altro servizio, 3 per un altro servizio e così via.

Puoi accedere ai percorsi proprio come puoi collegare a parti di un sito web. Ad esempio, per ottenere un elenco di tutti i post contrassegnati in "JavaScript" su Smashing Magazine, vai a https://www.smashingmagazine.com/tag/javascript/ . https://www.smashingmagazine.com/ è il root-endpoint e /tag/javascript è il percorso.

Per capire quali percorsi sono disponibili per te, devi consultare la documentazione dell'API. Ad esempio, supponiamo che tu voglia ottenere un elenco di repository da un determinato utente tramite l'API di Github. I documenti ti dicono di utilizzare il seguente percorso per farlo:

 /users/:username/repos

Eventuali due punti ( : ) su un percorso denotano una variabile. Dovresti sostituire questi valori con i valori effettivi di quando invii la tua richiesta. In questo caso, dovresti sostituire :username con il nome utente effettivo dell'utente che stai cercando. Se sto cercando il mio account Github, sostituirò :username con zellwk .

L'endpoint per ottenere un elenco dei miei repository su Github è questo:

 https://api.github.com/users/zellwk/repos

La parte finale di un endpoint è costituita dai parametri di query . Tecnicamente, i parametri di query non fanno parte dell'architettura REST, ma vedrai che molte API li usano. Quindi, per aiutarti a capire completamente come leggere e utilizzare le API, ne parleremo anche. I parametri di query ti danno la possibilità di modificare la tua richiesta con coppie chiave-valore. Iniziano sempre con un punto interrogativo ( ? ). Ogni coppia di parametri viene quindi separata da una e commerciale ( & ), in questo modo:

 ?query1=value1&query2=value2

Quando provi a ottenere un elenco dei repository di un utente su Github, aggiungi tre possibili parametri alla tua richiesta per modificare i risultati che ti vengono forniti:

Se desideri ottenere un elenco dei repository in cui ho eseguito il push di recente, puoi impostare l' sort su push .

 https://api.github.com/users/zellwk/repos?sort=pushed

Come fai a sapere se questo endpoint funziona? Bene, è ora di provarlo!

Testare gli endpoint con curl

Puoi inviare una richiesta con qualsiasi linguaggio di programmazione. Gli utenti JavaScript possono utilizzare metodi come l'API Fetch e il metodo Ajax di jQuery; Gli utenti di Ruby possono usare la classe Net::HTTP di Ruby, gli utenti di Python possono usare le richieste Python; e così via.

Per questo articolo, utilizzeremo l'utilità della riga di comando denominata cURL. Usiamo cURL perché le documentazioni API sono normalmente scritte con riferimento a cURL. Se capisci come utilizzare cURL, non avrai problemi a comprendere la documentazione dell'API. Quindi, puoi facilmente eseguire richieste con la tua lingua preferita.

Prima di continuare, assicurati di avere cURL installato sul tuo computer. Apri il tuo Terminale e digita curl -version . Questo comando controlla la versione di cURL che hai installato sul tuo sistema.

 curl --version

Se non hai cURL installato, riceverai un errore "comando non trovato". Se ricevi questo errore, dovrai installare curl prima di andare avanti.

Per utilizzare cURL, digita curl , seguito dall'endpoint per cui stai richiedendo. Ad esempio, per ottenere l'endpoint radice di Github, digita quanto segue:

 curl https://api.github.com

Dopo aver premuto invio, dovresti ricevere una risposta da Github simile a questa:

Per ottenere un elenco dei repository di un utente, modifichi l'endpoint nel percorso corretto, come abbiamo discusso sopra. Per ottenere un elenco dei miei repository, puoi usare questo comando:

 curl https://api.github.com/users/zellwk/repos

Se desideri includere parametri di query con cURL, assicurati di anteporre una barra rovesciata ( \ ) prima di ? e = caratteri. Questo perché ? e = sono caratteri speciali nella riga di comando. Devi usare \ prima di loro affinché la riga di comando li interpreti come caratteri normali:

 curl https://api.github.com/users/zellwk/repos\?sort\=pushed

Prova a utilizzare uno dei due comandi ed esegui una richiesta! Otterrai una risposta simile a quella che hai visto con il root-endpont di Github (ma con molti più dati).

JSON

JSON (JavaScript Object Notation) un formato comune per l'invio e la richiesta di dati tramite un'API REST. Anche la risposta che Github ti invia è formattata come JSON.

Un oggetto JSON ha l'aspetto di un oggetto JavaScript. In JSON, ogni proprietà e valore deve essere racchiuso tra virgolette doppie, in questo modo:

 { "property1": "value1", "property2": "value2", "property3": "value3" }

Torna all'anatomia di una richiesta

Hai appreso che una richiesta è composta da quattro parti.

1. Il punto finale
2. Il metodo
3. Le intestazioni
4. I dati (o il corpo)

Esaminiamo il resto di ciò che costituisce una richiesta.

Il metodo

Il metodo è il tipo di richiesta che invii al server. Puoi scegliere tra questi cinque tipi di seguito:

• GET
• POST
• PUT
• PATCH
• DELETE

Questi metodi forniscono un significato alla richiesta che stai facendo. Vengono utilizzati per eseguire quattro possibili azioni: Create , Read , Update ed Delete (CRUD).

L'API ti consente di sapere quale metodo di richiesta utilizzare per ciascuna richiesta. Ad esempio, per ottenere un elenco dei repository di un utente, è necessaria una richiesta GET :

È necessaria una richiesta GET per ottenere un elenco di repository da un utente. Per creare un nuovo repository Github, è necessaria una richiesta POST :

Puoi impostare il metodo di richiesta in cURL scrivendo -X o --request , seguito dal metodo di richiesta. Questo comando seguente tenta di creare un repository tramite cURL:

 curl -X POST https://api.github.com/user/repos

Prova a eseguire questa richiesta. Riceverai una risposta che ti dice che è richiesta l'autenticazione. (Maggiori informazioni sull'autenticazione più avanti).

 { "message": "Requires authentication", "documentation_url": "https://developer.github.com/v3" }

Le intestazioni

Le intestazioni vengono utilizzate per fornire informazioni sia al client che al server. Può essere utilizzato per molti scopi, come l'autenticazione e la fornitura di informazioni sul contenuto del corpo. È possibile trovare un elenco di intestazioni valide su Riferimento intestazioni HTTP di MDN.

Le intestazioni HTTP sono coppie proprietà-valore separate da due punti. L'esempio seguente mostra un'intestazione che indica al server di aspettarsi contenuto JSON.

 "Content-Type: application/json". Missing the opening ".

Puoi inviare intestazioni HTTP con curl tramite l'opzione -H o --header . Per inviare l'intestazione sopra all'API di Github, usi questo comando:

 curl -H "Content-Type: application/json" https://api.github.com

(Nota: l'intestazione Content-Type non è un requisito per il funzionamento dell'API di Github. Questo è solo un esempio per illustrare come utilizzare un'intestazione con cURL).

Per visualizzare le intestazioni che hai inviato, puoi utilizzare l'opzione -v o --verbose mentre invii la richiesta, in questo modo:

 curl -H "Content-Type: application/json" https://api.github.com -v 

Qui, * si riferisce a informazioni aggiuntive fornite da cURL. > si riferisce alle intestazioni delle richieste e < si riferisce alle intestazioni delle risposte.

I Dati (o “Ente”)

I dati (a volte chiamati "corpo" o "messaggio") contengono informazioni che si desidera inviare al server. Questa opzione viene utilizzata solo con le richieste POST , PUT , PATCH o DELETE .

Per inviare dati tramite cURL, puoi utilizzare l'opzione -d o --data :

 curl -X POST <URL> -d property1=value1

Per inviare più campi di dati, puoi creare più opzioni -d :

 curl -X POST <URL> -d property1=value1 -d property2=value2

Se ha senso, puoi suddividere la tua richiesta in più righe \ per facilitarne la lettura:

 curl -X POST <URL> \ -d property1=value1 \ -d property2=value2

Se sai come far girare un server, puoi creare un'API e testare i tuoi dati. Se non lo sai, ma ti senti abbastanza coraggioso da provare, puoi seguire questo articolo per imparare a creare un server con Node, Express e MongoDB

Se non vuoi far girare il tuo server, puoi andare su Requestbin.com ( è gratis! ) e cliccare su “crea endpoint”. Ti verrà fornito un URL che puoi utilizzare per testare le richieste, come https://requestb.in/1ix963n1 mostrato nell'immagine qui sotto.

Assicurati di creare il tuo raccoglitore di richieste se desideri testare la tua richiesta. I contenitori delle richieste rimangono aperti solo per 48 ore dopo la sua creazione. Quando leggerai questo articolo, il cestino che ho creato sopra sarà scomparso da tempo.

Ora, prova a inviare alcuni dati al tuo cestino delle richieste, quindi aggiorna la pagina web del tuo cestino. Vedrai alcuni dati, come questo:

 curl -X POST https://requestb.in/1ix963n1 \ -d property1=value1 \ -d property2=value2 

Per impostazione predefinita, cURL invia i dati come se fossero inviati tramite "campi modulo" in una pagina. Se desideri inviare dati JSON, dovrai impostare Content-Type su application/json e dovrai formattare i tuoi dati come un oggetto JSON, in questo modo:

 curl -X POST https://requestb.in/1ix963n1 \ -H "Content-Type: application/json" \ -d '{ "property1":"value1", "property2":"value2" }' 

E questo è (quasi!) tutto ciò che devi sapere sulla struttura di una richiesta.

Ora, ricorda quando hai provato a inviare una richiesta POST tramite l'API di Github, hai ricevuto un messaggio che dice "Richiede autenticazione"? Bene, questo perché non sei autorizzato a eseguire la richiesta POST !

Autenticazione

Non consentiresti a nessuno di accedere al tuo conto bancario senza il tuo permesso, vero? Sulla stessa linea di pensiero, gli sviluppatori mettono in atto misure per assicurarti di eseguire azioni solo quando sei autorizzato a farlo. Questo impedisce agli altri di impersonarti.

Poiché le richieste POST , PUT , PATCH e DELETE alterano il database, gli sviluppatori le mettono quasi sempre dietro un muro di autenticazione. In alcuni casi, una richiesta GET richiede anche l'autenticazione (come quando accedi al tuo conto bancario per controllare il tuo saldo attuale, ad esempio).

Sul web ci sono due modi principali per autenticarsi:

1. Con un nome utente e una password (detta anche autenticazione di base)
2. Con un gettone segreto

Il metodo del token segreto include oAuth, che ti consente di autenticarti con i social network come Github, Google, Twitter, Facebook, ecc.

Per questo articolo imparerai a utilizzare l'autenticazione di base solo con un nome utente e una password. Se sei interessato all'autenticazione con oAuth, ti suggerisco di leggere "Cosa devi sapere su OAuth2 e accedere con Facebook" di Zack Grossbart.

Per eseguire un'autenticazione di base con cURL, puoi usare l'opzione -u , seguita dal tuo nome utente e password, in questo modo:

 curl -x POST -u "username:password" https://api.github.com/user/repos

Prova ad autenticarti con il tuo nome utente e password nella richiesta sopra. Una volta completata l'autenticazione, vedrai la risposta cambiare da "Richiede autenticazione" a "Problemi di analisi JSON".

Questo perché devi ancora fornire tutti i dati (richiesti da tutte le richieste POST , PUT , PATCH e DELETE ) al server.

Con le conoscenze che hai imparato finora, dovresti essere in grado di modificare il codice sopra per creare un repository Github tramite il tuo cURL. Ti lascio a provarlo tu stesso!

Ora parliamo di codici di stato HTTP e messaggi di errore.

Codici di stato HTTP e messaggi di errore

Alcuni dei messaggi che hai ricevuto in precedenza, come "Richiede autenticazione" e "Problemi durante l'analisi di JSON", sono messaggi di errore. Appaiono solo quando qualcosa non va nella tua richiesta. I codici di stato HTTP consentono di comunicare rapidamente lo stato della risposta. La gamma da 100+ a 500+. In generale, i numeri seguono le seguenti regole:

1. 200+ significa che la richiesta è andata a buon fine .
2. 300+ significa che la richiesta viene reindirizzata a un altro URL
3. 400+ significa che si è verificato un errore che ha origine dal client
4. 500+ significa che si è verificato un errore che ha origine dal server

Puoi eseguire il debug dello stato di una risposta con l'opzione verbose ( -v o --verbose ) o l'opzione head ( -I o --head ).

Ad esempio, se hai provato ad aggiungere -I a una richiesta POST senza fornire il tuo nome utente e password, otterrai un codice di stato 401 (non autorizzato):

Se la tua richiesta non è valida perché i tuoi dati sono errati o mancanti, di solito ricevi un codice di stato 400 (Bad Request).

Per ottenere maggiori informazioni sui codici di stato HTTP specifici, è possibile consultare il Riferimento sullo stato HTTP di MDN.

Versioni API

Gli sviluppatori aggiornano le loro API di volta in volta. A volte, l'API può cambiare così tanto che lo sviluppatore decide di aggiornare la propria API a un'altra versione. Se ciò accade e la tua applicazione si interrompe, di solito è perché hai scritto il codice per un'API precedente, ma la tua richiesta punta all'API più recente.

Puoi richiedere una versione specifica dell'API in due modi. Il modo in cui scegli dipende da come viene scritta l'API.

Questi due modi sono:

1. Direttamente nell'endpoint
2. In un'intestazione di richiesta

Twitter, ad esempio, utilizza il primo metodo. Al momento in cui scrivo, l'API di Twitter è alla versione 1.1, il che è evidente attraverso il suo endpoint:

 https://api.twitter.com/1.1/account/settings.json

Github, d'altra parte, usa il secondo metodo. Al momento della scrittura, l'API di Github è alla versione 3 e puoi specificare la versione con un'intestazione Accept :

 curl https://api.github.com -H Accept:application/vnd.github.v3+json

Avvolgendo

In questo articolo, hai imparato cos'è un'API REST e come utilizzare cURL per eseguire una richiesta con i metodi GET , POST , PUT , PATCH e DELETE . Inoltre, hai anche imparato come autenticare le tue richieste con l'opzione -u e cosa significano gli stati HTTP.

Spero che questo articolo ti abbia aiutato a imparare abbastanza sulle API REST e che tu possa usarle in modo fluido mentre crei le tue applicazioni. Sentiti libero di fare un salto sul mio blog o di lasciare i tuoi commenti qui sotto se hai domande.