Le basi di REST e RESTful API Development

Gli sviluppatori web parlano spesso dei principi REST e dell'architettura dei dati RESTful, poiché è un aspetto cruciale dello sviluppo moderno, ma a volte può essere incredibilmente confuso. REST non è una tecnologia in sé, ma piuttosto un metodo per creare API con determinati principi organizzativi . Questi principi guidano gli sviluppatori e creano un ambiente più universale per l'elaborazione delle richieste API.

In questo post, mi piacerebbe spiegare le pratiche di sviluppo RESTful da una prospettiva a volo d'uccello. Voglio affrontare il cosa piuttosto che il come . Anche se parlerò di entrambe le aree, questo post è pensato per tutti coloro che sono interessati allo sviluppo web, ma semplicemente non è in grado di cogliere il concetto delle API REST.

REST per gli sviluppatori Web

L'acronimo REST sta per Representational State Transfer . Questo può sembrare un po 'confuso, e la voce wiki lo rende ancora più confuso. Ma è possibile semplificare la terminologia.

REST è solo una serie di linee guida e stili architettonici utilizzati per la trasmissione dei dati . Viene comunemente applicato alle applicazioni Web, ma può anche passare i dati al software.

L'acronimo API sta per Application Programming Interface, che sono metodi di connessione con altre librerie o applicazioni . Windows ha più API e Twitter ha anche un'API Web, sebbene eseguano compiti diversi con obiettivi diversi.

Combinando tutto insieme, le API RESTful sono API che seguono l'architettura REST.

Qual è esattamente l'architettura REST?

Questo è dove è difficile stabilire specifiche. Tuttavia ci sono alcune costanti architettoniche, come ad esempio:

• Coerenza su tutta l'API
• Esistenza stateless, cioè nessuna sessione lato server
• Utilizzo dei codici di stato HTTP ove appropriato
• Utilizzo di endpoint URL con una gerarchia logica
• Controllo delle versioni nell'URL anziché nelle intestazioni HTTP

Non ci sono linee guida troppo specifiche come le specifiche HTML5 del W3C che potrebbero causare confusione e un miasma di incertezza intorno alla terminologia REST.

Inoltre, l'elenco di cui sopra non deve essere considerato una regola rigida, anche se è vero per la maggior parte delle moderne API RESTful.

REST è una metodologia leggera che lo rende perfetto per i dati HTTP. Questo è il motivo per cui REST è diventato così popolare sul Web e perché è ampiamente considerato la scelta migliore per lo sviluppo dell'API.

Come dice Vinay Sahni, "un'API è l'interfaccia utente di uno sviluppatore." Tutto dovrebbe essere facile da usare e offrire un'esperienza utente eccezionale. Le API RESTful mirano a fare proprio questo.

Key Takeaway per le API RESTful

Questi suggerimenti sono nel contesto delle API strettamente per le applicazioni web . Ciò significa che HTTP è un requisito e spesso significa che i dati dell'API sono ospitati su un server esterno . Esaminiamo in che modo le API RESTful funzionano sul lato dell'utente API.

L'utente API è lo sviluppatore web che può creare uno script che si connette a un server API esterno, quindi i dati necessari vengono passati su HTTP. Lo sviluppatore può quindi visualizzare i dati sul proprio sito Web senza avere accesso personale al server esterno (ad esempio, estrarre i dati di Twitter).

In generale, ci sono quattro comandi usati per accedere alle API RESTful :

1. GET per recuperare un oggetto
2. POST per la creazione di un nuovo oggetto
3. PUT per modificare o sostituire un oggetto
4. DELETE per la rimozione di un oggetto

Ognuno di questi metodi dovrebbe essere passato con la chiamata API per dire al server cosa fare.

La stragrande maggioranza delle API Web consente solo alle richieste GET di estrarre dati da un server esterno. L'autenticazione è facoltativa, ma sicuramente è una buona idea quando si autorizzano comandi potenzialmente dannosi come PUT o DELETE .

Tuttavia non molte API RESTful arrivano fino a questo punto. Considera Pokéapi che è un database di API Pokémon gratuito. È aperto al pubblico con limiti di frequenza decenti (limitando gli utenti a un certo numero di richieste API per un periodo di tempo), ma consente solo il metodo GET per l'accesso alle risorse. Questo può essere definito colloquialmente un'API di solo consumo .

Anche i tipi di ritorno sono importanti e dovrebbero mantenere l'omogeneità per tutte le risorse. JSON è un tipo di ritorno popolare con specifiche online che spiegano le corrette strutture di dati.

Le API RESTful utilizzano nomi per oggetti API e verbi per l'esecuzione di azioni su tali oggetti. L'autenticazione può far parte di questo, anche la limitazione della velocità può far parte di questo. Ma un'API molto semplice può farcela senza troppe preoccupazioni per le limitazioni degli utenti.

Accesso alle risorse API

Le API pubbliche sono generalmente accessibili da indirizzi di siti Web diretti . Ciò significa che la struttura dell'URL è importante e dovrebbe essere utilizzata solo per le richieste API.

Alcuni URL possono includere una directory di prefissi come /v2/ per una versione aggiornata 2 di un'API precedente. Questo è comune per gli sviluppatori che non vogliono svalutare la loro API 1.x, ma desiderano comunque offrire la struttura più recente.

Mi è piaciuto molto questo post riguardante le strutture URL di base e gli esempi di altri servizi.

Si noti che i dati di ritorno dell'endpoint cambieranno radicalmente in base al metodo HTTP . Ad esempio, GET recupera il contenuto, mentre POST crea nuovo contenuto. La richiesta potrebbe indicare lo stesso endpoint, ma il risultato potrebbe essere molto diverso.

Esaminare gli esempi online può aiutarti a capire meglio i concetti. Abbiamo già visto Pokeapi, ma qui ci sono alcuni esempi di API reali da esaminare:

• API Reddit
• API GitHub
• Flickr API
• API Pinterest

Costruire la tua API

Il processo di costruzione della tua API non dovrebbe essere preso alla leggera, ma non è così complicato come potresti pensare. Ci vuole una comprensione dei modelli di progettazione delle API e delle migliori pratiche per costruire qualcosa di valore reale.

Ogni API deve connettersi al tuo server per restituire dati di qualche tipo. Non solo hai bisogno di scrivere codice per farlo, ma hai anche bisogno di formattare i dati di ritorno. Altri requisiti potenziali includono l' autenticazione e la limitazione della velocità, quindi la creazione di un'API non è certamente per i deboli di cuore.

Ma diamo un'occhiata ad alcuni principi di base dell'architettura API.

Costruisci endpoint

Un aspetto dello sviluppo dell'API sta creando endpoint . Quando crei risorse, vuoi usare nomi, non verbi. Ciò significa che i dati API devono restituire una persona, un luogo o una cosa, il più delle volte è una cosa con attributi specifici (ad esempio un tweet e tutti i suoi metadati).

Può essere difficile imparare a nominare nomi, ma questo è un aspetto cruciale dello sviluppo dell'API. La semplificazione è la migliore quando possibile.

Un grande dibattito è singolare contro nomi plurali . Se stavi creando un'API di Twitter potresti avere prima il gruppo di oggetti (cioè tweet), quindi il secondo oggetto dell'oggetto (cioè l'ID tweet).

 $ / tweet / 15032934882934 $ / tweets / 15032934882934 

In questo caso, direi che la forma singolare sembra migliore. Questo è vero soprattutto quando viene restituita una sola risorsa. Ma non esiste una risposta corretta al 100%, quindi fai tutto quello che si adatta meglio al tuo progetto.

Imposta il tipo di reso

Un'altra considerazione è il tipo di dati di ritorno . La maggior parte degli utenti Web si aspetta contenuti JSON, quindi è probabilmente l'opzione migliore. XML è un'altra scelta se vuoi offrire entrambi. Tuttavia, JSON è il tipo di ritorno API fondamentale tra gli sviluppatori web.

C'è molto di più che va nello sviluppo dell'API, quindi consiglio di giocare prima con le API. In questo modo puoi vedere come altri sviluppatori sviluppano le loro API e, si spera, acquisirai familiarità con i requisiti tipici.

Se hai appena iniziato, ti preghiamo di prendere in considerazione la possibilità di sfogliare questi tutorial di sviluppo:

• Sito di esercitazione dell'API REST
• Scrivere una semplice API REST
• Costruire un servizio Web RESTful

Ulteriori risorse

Il modo migliore per imparare lo sviluppo di app Web è attraverso la pratica. La teoria concessa merita sempre di essere studiata, perché ti consente di conversare con gli sviluppatori e capire come funzionano le cose.

Ma un buon punto di partenza per lo sviluppo dell'API è la prima connessione con altre API . Scopri le basi delle connessioni lato client e da lì puoi passare allo sviluppo dell'API lato server creando da zero la tua API.

Se questo è il tuo obiettivo, ti preghiamo di considerare le seguenti risorse per aiutarti nel tuo viaggio.

Libri

• Regolamento di progettazione dell'API REST
• API Web RESTful
• Ricettario dei servizi Web RESTful
• REST non disturbato: una guida alla progettazione dell'API perfetta

articoli

• Guida per principianti su HTTP e REST
• Creazione di un'API RESTful
• Guida ai nomi delle risorse RESTful
• Creazione di un'API REST utilizzando lo stack MEAN