Impostare ed avviare un'API REST fittizia utilizzando json-server

Italian (Italiano) translation by Francesco Turlon (you can also view the original English article)

In questa guida vedrete come iniziare a impostare e usare un server API REST fittizio utilizzando json-server, che potrete sfruttare sviluppando applicazioni mobile e web. Questo tutorial dà per scontato che abbiate una conoscenza basilare di JSON e richieste HTTP.

Cos'è REST?

REST sta per Representational State Transfer. È uno stile di architettura per il design di applicazioni connesse. Utilizza semplice HTTP per consentire la comunicazione tra macchine. Quindi invece di usare un URL per gestire informazioni utente, REST invia una richiesta HTTP come GET, POST, DELETE, etc. a un URL per la manipolazione dei dati.

Per esempio, invece di fare una richiesta GET ad un URL come /deleteuser?id=10, la richiesta sarà DELETE /user/10.

Perché abbiamo bisogno di una falsa API REST?

Le API REST costituiscono il back end di applicazioni mobile e web. Nello sviluppo di applicazioni a volte non avrete pronte delle API REST utilizzabili a scopo di sviluppo. Per vedere l'applicazione mobile e web in azione, abbiamo bisogno di un server che fornisca dei dati JSON fittizi.

Questo è il momento in cui la falsa API REST entra in gioco. json-server fornisce funzionalità per impostare un server fittizio API REST con minimo sforzo.

Guida introduttiva

Per iniziare ad usare json-server, installate il package usando Node Package Manager (npm).

npm install -g json-server

Create un file JSON fittizio con dati che vi potrebbero servire. Per esempio abbiamo bisogno di alcuni dati JSON contenenti informazioni utente come id, nome, luogo, etc. Così creeremo un file chiamato info.json con le informazioni JSON seguenti:

{
    "users": [{
        "id": 1,
        "name": "roy",
        "location": "india"
    }, {
        "id": 2,
        "name": "sam",
        "location": "wales"
    }]
}

Dal terminale, avviate il server json con info.json come sorgente dati e dovreste avere l'API REST funzionante all'indirizzo http://localhost:3000.

json-server info.json

Testare gli Endpoints dell'API REST

Dal momento che il nostro server API REST fittizio è installato e funzionante, vediamo come accedere all'API REST usando un client. Sto usando il client REST Postman per eseguire chiamate API.

Richiesta GET

Cominciamo facendo una richiesta GET all'URL REST. Dentro al file json, abbiamo definito un endpoint users che contiene informazioni relative agli utenti. Nel fare una richiesta GET all'URL http://localhost:3000/users, dovrebbe mostrare i dati esistenti.

[
  {
    "id": 1,
    "name": "roy",
    "location": "india"
  },
  {
    "id": 2,
    "name": "sam",
    "location": "wales"
  }
]

Richiesta POST

Per aggiungere nuovi dati a quelli esistenti faremo una richiesta POST all'URL http://localhost:3000/users. Ecco come apparirà la richiesta POST:

Provate a fare una richiesta GET e dovreste avere i nuovi dati aggiunti nel file info.json.

[
  {
    "id": 1,
    "name": "roy",
    "location": "india"
  },
  {
    "id": 2,
    "name": "sam",
    "location": "wales"
  },
  {
    "name": "ii",
    "location": "la",
    "id": 7
  },
  {
    "name": "Shona",
    "location": "LA",
    "id": 8
  },
  {
    "name": "Shona",
    "location": "LA",
    "id": 9
  }
]

Richiesta DELETE

Per cancellare un inserimento dati da json-server, dovrete inviare una richiesta DELETE all'endpoint API con l'user Id. Per esempio, per eliminare l'utente con Id 1, dovrete inviare una richiesta DELETE all'endpoint http://localhost:3000/users/1. Una volta eliminato, provate a fare una richiesta GET e l'utente con Id 1 non dovrebbe essere riportato nel JSON restituito.

Richiesta PATCH

Per aggiornare un dato esistente, dovrete inviare una richiesta PATCH con i dettagli necessari per quel particolare dato. Per esempio, per aggiornare i dettagli dell'utente con Id 2, invieremo una richiesta PATCH all'URL http://localhost:3000/users/2 come mostrato:

Cercare API REST json-server

Usando le API REST json-server, potete cercare tra i dati per trovarne secondo certi criteri. Per esempio, per trovare utenti con un nome particolare dovrete inviare una richiesta GET all'URL API REST nel modo seguente:

Sending a GET request to the REST API URL

Come mostrato nell'immagine soprastante, inviando una richiesta GET all'URL http://localhost:3000/users?name=Shona avrete restituiti gli utenti con nome Shona. Analogamente, per cercare utenti con qualsiasi altro campo, dovrete aggiungere quel campo alla query.

Per eseguire una ricerca di testo completa attraverso l'endpoint API REST, dovrete aggiungere la stringa di ricerca insieme al parametro q all'endpoint. Per esempio, per cercare utenti con informazioni contenenti la stringa di ricerca s, la richiesta dovrà essere la seguente:

Full Text Search in json-server REST API

Gestire l'impaginazione

Durante la visualizzazione di una griglia dati impaginata, potrebbe essere necessario recuperare alcuni dati sulla base dell'impaginazione. In tali scenari, json-server fornisce la funzionalità di impaginare i dati JSON. Di default, il conteggio dei dati restituiti da json-server è 10. Possiamo definire esplicitamente questo limite usando il parametro _limit.

http://localhost:3000/users?_limit=5

Una richiesta GET all'URL soprastante darebbe cinque risultati. Ora, per impaginare i dati, dobbiamo aggiungere un altro parametro _page all'URL. _page definisce la pagina che deve essere interrogata per restituire i dati.

http://localhost:3000/users?_limit=5&_page=2

Una richiesta GET all'URL qui sopra restituirebbe la seconda pagina del set di dati con cinque records per pagina. Cambiando la variabile _page, possiamo ottenere i records della pagina richiesti.

Gestione dell'ordinamento

json-server fornisce la funzionalità di ordinare i dati ottenuti. Possiamo ordinare i dati fornendo il nome della colonna che dobbiamo sistemare e l'ordine in cui i dati dovranno essere sistemati. Di default i dati vengono riordinati in ordine ascendente. Possiamo fornire il nome della colonna nell'URL endpoint usando la keyword _sort e definire l'ordine usando la keyword _order. Di seguito un URL d'esempio:

http://localhost:3000/users?_sort=id&_order=DESC

L'URL soprastante ordinerà i dati in base alla colonna Id e verrà ordinata in ordine decrescente.

Gestione degli operatori

json-server fornisce inoltre la funzionalità di supportare operatori, come trovare un dato tramite Id in un range di due valori o un altro dato che corrisponda a una particolare espressione regolare.

Per trovare un dato all'interno di un particolare range, possiamo fare uso degli operatori _gte e _lte. Per esempio, per trovare utenti con Id maggiore di 1 e inferiore a 2, fate una richiesta GET all'URL http://localhost:3000/users?id_gte=1&id_lte=2 come mostrato:

Handling Less Than Greater Than Operators

Se vogliamo cercare nomi che iniziano con una determinata lettera, possiamo usare espressioni regolari. Per esempio, per cercare nomi che iniziano con le lettere sa, useremo l'operatore _like e faremo una richiesta GET all'URL http://localhost:3000/users?name_like=^sa.

Handling Regular Expressions In Operators

Conclusione

In questo tutorial avete visto come usare le API Rest json-server per creare un database fittizio per un utilizzo rapido. Avete imparato come iniziare ad usare json-server e interrogare l'URL per aggiungere, modificare e cancellare dati. Avete visto come impaginare, ordinare e cercare i dati appena creati. Avete inoltre visto come usare gli operatori per cercare dati attraverso espressioni regolari.

Avete usato json-server o qualche altro server API REST per la creazione di dati di test? Com'è stata la vostra esperienza? Fateci conoscere le vostre considerazioni nei commenti in basso.