Share
Se hai trascorso un po 'di tempo con lo sviluppo web moderno, avrai trovato termini come REST e API. Se hai sentito parlare di questi termini o lavori con le API ma non hai una comprensione completa di come funzionano o di come creare la tua API, questa serie è per te.
In questa serie di tutorial, inizieremo con una panoramica dei principi e dei concetti REST. Quindi andremo a creare la nostra API completa che gira su un server Node.js Express e si connette a un database MySQL. Dopo aver terminato questa serie, dovresti sentirti sicuro di creare la tua API o approfondire la documentazione di un'API esistente.
Per ottenere il massimo da questo tutorial, dovresti avere già una conoscenza base della riga di comando, conoscere i fondamenti di JavaScript e avere Node.js installato a livello globale.
Trasferimento dello stato di rappresentanza, o RIPOSO, descrive uno stile architettonico per i servizi web. REST è costituito da un insieme di standard o vincoli per la condivisione di dati tra sistemi diversi e i sistemi che implementano REST sono noti come RESTful. REST è un concetto astratto, non un linguaggio, una struttura o un tipo di software.
Un'analogia allentata per REST manterrebbe una raccolta di vinili rispetto all'utilizzo di un servizio di musica in streaming. Con la raccolta in vinile fisica, ogni record deve essere duplicato nella sua interezza per condividere e distribuire copie. Con un servizio di streaming, tuttavia, la stessa musica può essere condivisa in perpetuo tramite un riferimento ad alcuni dati come il titolo di un brano. In questo caso, la musica in streaming è un servizio RESTful e la raccolta in vinile è un servizio non RESTful.
Un API è un'interfaccia di programmazione dell'applicazione, che è un'interfaccia che consente ai programmi software di comunicare tra loro. UN API RESTful è semplicemente un'API che aderisce ai principi e ai vincoli di REST. In un'API Web, un server riceve un richiesta attraverso un endpoint URL e invia a risposta in cambio, che è spesso dati in un formato come JSON.
Sei vincoli guida definiscono l'architettura REST, descritta di seguito.
Avrai già familiarità con il fatto che tutti i siti web hanno URL che iniziano con http (o https per la versione sicura). HyperText Transfer Protocol, o HTTP, è il metodo di comunicazione tra client e server su Internet.
Lo vediamo ovviamente nella barra degli URL dei nostri browser, ma HTTP può essere utilizzato per qualcosa di più della semplice richiesta di siti Web dai server. Quando si accede a un URL sul Web, si sta effettivamente facendo a OTTENERE richiesta su quella risorsa specifica e il sito Web che vedi è il corpo della risposta. Andremo oltre OTTENERE e altri tipi di richieste a breve.
HTTP funziona aprendo a TCP (Transmission Control Protocol) connessione a una porta del server (80 per http, 443 per https) per effettuare una richiesta e il server di ascolto risponde con uno stato e un corpo.
Una richiesta deve essere composta da un URL, un metodo, informazioni di intestazione e un corpo.
Esistono quattro principali metodi HTTP, denominati anche verbi HTTP, che vengono comunemente utilizzati per interagire con le API Web. Questi metodi definiscono l'azione che verrà eseguita con qualsiasi risorsa data.
I metodi di richiesta HTTP corrispondono vagamente al paradigma di CRUD, che sta per Crea, aggiorna, leggi, cancella. Sebbene CRUD si riferisca a funzioni utilizzate nelle operazioni di database, possiamo applicare tali principi di progettazione ai verbi HTTP in un'API RESTful.
| Azione | Metodo di richiesta | Definizione |
|---|---|---|
| Leggere | OTTENERE | Recupera una risorsa |
| Creare | INVIARE | Crea una nuova risorsa |
| Aggiornare | METTERE | Aggiorna una risorsa esistente |
| Elimina | ELIMINA | Elimina una risorsa |
OTTENERE è un'operazione sicura, di sola lettura che non altera lo stato di un server. Ogni volta che si preme un URL nel browser, ad esempio https://www.google.com, stai inviando un OTTENERE richiesta ai server di Google.
INVIARE è usato per creare una nuova risorsa. Un esempio familiare di INVIARE sta registrandosi come utente su un sito Web o un'app. Dopo aver inviato il modulo, a INVIARE richiesta con l'utente i dati potrebbero essere inviati al server, che quindi scriverà tali informazioni in un database.
METTERE aggiorna una risorsa esistente, che potrebbe essere utilizzata per modificare le impostazioni di un utente esistente. diversamente da INVIARE, METTERE è idempotente, il che significa che la stessa chiamata può essere fatta più volte senza produrre un risultato diverso. Ad esempio, se hai inviato lo stesso INVIARE richiesta di creare un nuovo utente in un database più volte, creerebbe un nuovo utente con gli stessi dati per ogni richiesta effettuata. Tuttavia, usando lo stesso METTERE richiesta sullo stesso utente produrrebbe continuamente lo stesso risultato.
ELIMINA, come suggerisce il nome, eliminerà semplicemente una risorsa esistente.
Una volta che una richiesta passa dal client al server, il server invierà una risposta HTTP, che includerà i metadati relativi alla risposta noti come intestazioni e al corpo. La prima e più importante parte della risposta è il codice di stato, che indica se una richiesta ha avuto esito positivo, se si è verificato un errore o se deve essere intrapresa un'altra azione.
Il codice di risposta più noto che conoscerai è 404, che significa Non trovato. 404 è parte del 4xx classe di codici di stato, che indicano errori del client. Esistono cinque classi di codici di stato che contengono ciascuna un intervallo di risposte.
Accentsconagua
1xx: Informazione2xx: Successo3xx: Reindirizzamento4xx: Errore del client5xx: Errore del serverAltre risposte comuni che potresti conoscere sono 301 spostati in modo permanente, che viene utilizzato per reindirizzare i siti Web a nuovi URL e 500 Errore interno del server, che è un errore che si presenta frequentemente quando qualcosa di inaspettato è accaduto su un server che rende impossibile soddisfare la richiesta prevista.
Per quanto riguarda le API RESTful e i relativi verbi HTTP corrispondenti, tutte le risposte dovrebbero essere nel 2xx gamma.
| Richiesta | Risposta |
|---|---|
OTTENERE | 200 (OK) |
INVIARE | 201 (Creato) |
METTERE | 200 (OK) |
ELIMINA | 200 (OK), 202 (Accettato), o 204 (Nessun contenuto) |
200 OK è la risposta che indica che una richiesta ha esito positivo. Viene utilizzato come risposta quando si invia un OTTENERE o METTERE richiesta. INVIARE restituirà a 201 creato per indicare che è stata creata una nuova risorsa, e ELIMINA ha alcune risposte accettabili, che indicano che la richiesta è stata accettata (202), oppure non ci sono contenuti da restituire perché la risorsa non esiste più (204).
Possiamo testare il codice di stato di una richiesta di risorsa utilizzando cURL, che è uno strumento da riga di comando utilizzato per il trasferimento di dati tramite URL. utilizzando arricciare, seguito dal -io o --includere bandiera, invierà a OTTENERE richiedere un URL e visualizzare le intestazioni e il corpo. Possiamo testare questo aprendo il programma della riga di comando e testando cURL con Google.
curl -i https://www.google.com Il server di Google risponderà con quanto segue.
Data HTTP / 2 200: martedì, 14 agosto 2018 05:15:40 GMT scade: -1 cache-control: private, max-age = 0 content-type: text / html; charset = ISO-8859-1 ...
Come possiamo vedere, il arricciare richiesta restituisce più intestazioni e l'intero corpo HTML della risposta. Dal momento che la richiesta è andata a buon fine, la prima parte della risposta è il 200 codice di stato, insieme alla versione di HTTP (questo sarà HTTP / 1.1 o HTTP / 2).
Poiché questa particolare richiesta sta restituendo un sito Web, il tipo di contenuto (Tipo MIME) che viene restituito text / html. In un'API RESTful, probabilmente lo vedrai application / json per indicare la risposta è JSON.
È interessante notare che possiamo vedere un altro tipo di risposta inserendo un URL leggermente diverso. Fai un arricciare su Google senza il www.
curl -i https://google.com Posizione HTTP / 2 301: https://www.google.com/ content-type: text / html; charset = UTF-8
Google reindirizza google.com a www.google.com, e usa a 301 risposta per indicare che la risorsa deve essere reindirizzata.
Quando viene creata un'API su un server, i dati contenuti sono accessibili tramite endpoint. Un endpoint è l'URL della richiesta che può accettare ed elaborare il OTTENERE, INVIARE, METTERE, o ELIMINA richiesta.
Un URL API consisterà nella radice, nel percorso e nella stringa di query facoltativa.
https://api.example.com o https://api.example.com/v2: La radice dell'API, che può essere costituita da protocollo, dominio e versione./ utenti /o / utenti / 5: Posizione univoca della risorsa specifica.?location = Chicago & età = 29: Coppie di valori chiave facoltativi utilizzati per l'ordinamento, il filtraggio e l'impaginazione.limite filtrare le risposte per includere solo dieci risultati.https://api.example.com/users?limit=10
In genere, quando le persone fanno riferimento a un'API come API RESTful, fanno riferimento alle convenzioni di denominazione utilizzate per creare endpoint dell'URL dell'API. Alcune importanti convenzioni per un'API RESTful standard sono le seguenti:
5, noi useremmo / utenti / 5, non / User / 5..jSON.Inserisci e Elimina non dovrebbe apparire in un URL REST. Per aggiungere un nuovo utente, devi semplicemente inviare un INVIARE richiesta a / utenti, non qualcosa come / utenti / aggiungi. L'API dovrebbe essere sviluppata per gestire più tipi di richieste allo stesso URL.Tutte queste convenzioni sono linee guida, in quanto non ci sono rigorosi standard REST da seguire. Tuttavia, l'utilizzo di queste linee guida renderà la tua API coerente, familiare e di facile lettura e comprensione.
In questo articolo abbiamo appreso quali sono le API REST e RESTful, come funzionano i metodi di richiesta HTTP e i codici di risposta, la struttura di un URL dell'API e le convenzioni API RESTful comuni. Nel prossimo tutorial, impareremo come utilizzare tutta questa teoria configurando un server Express con Node.js e costruendo la nostra API.
