> For the complete documentation index, see [llms.txt](https://checksound.gitbook.io/tecnologie5/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://checksound.gitbook.io/tecnologie5/web-services/rest.md).

# REST - Representation State Transfer

{% embed url="<https://medium.com/nerd-for-tech/designing-a-rest-api-3a070398750f#0d66>" %}

{% embed url="<https://www.youtube.com/watch?v=lsMQRaeKNDk>" %}

{% embed url="<https://www.youtube.com/watch?v=pRS9LRBgjYg>" %}

REST è l'acronimo di **RE**presentation **S**tate **T**ransfer. E' uno stile architetturale per i sistemi distribuiti e fu presentato da Roy Fielding nel 2000 in una sua famosa [dissertazione](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm).

In simplest words, in the REST **architectural style**, data and functionality are considered resources and are accessed using Uniform Resource Identifiers (URIs). The resources are acted upon by using a set of simple, well-defined operations. The clients and servers exchange representations of resources by using a standardized interface and protocol – typically HTTP.

Resources are decoupled from their representation so that their content can be accessed in a variety of formats, such as HTML, XML, plain text, PDF, JPEG, JSON, and others. Metadata about the resource is available and used, for example, to control caching, detect transmission errors, negotiate the appropriate representation format, and perform authentication or access control. And most importantly, every interaction with a resource is stateless.

All these principles help RESTful applications to be simple, lightweight, and fast.

### ESEMPIO REST

Vediamo prima con un esempio cos'è REST, partendo da un servizio free che rispetta l'architettura di un servizio REST, cioè permette di interrogare, avere risposte dal server tramite semplici chiamate HTTP a delle url che identificano in modo univoco le risorse.

{% embed url="<https://gorest.co.in/>" %}

#### RICHIESTA ACCESS TOKEN

Per fare le richieste è necessario avere un **access token**, che vi viene dato dal servizio quando vi autenticate.

Cliccate sul pulsante `Login` in alto a destra

![Home servizio -clicco su Login](https://677719810-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LyjOfAs732TO1n80App%2F-M1of6ZCNANtHTHaqUI3%2F-M1oi10BYtvOO-ibCdQm%2Flogin1.PNG?alt=media\&token=417cff08-18ec-4720-b447-eb57d2896605)

Selezionate il servizio si autenticazione (di terze parti):

![Selezione servizio di autenticazione](https://677719810-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LyjOfAs732TO1n80App%2F-M1of6ZCNANtHTHaqUI3%2F-M1oiFlp7qHsEDVGRF83%2FLogin2.PNG?alt=media\&token=00d0d973-3bb9-426a-9db4-5e4e9b94b516)

Ora accedete il servizio vi ridirezione sulla pagina contenente l'**Access Token** che vi permette di sfruttare le API REST del servizio.

![Pagina informazioni con Access Token](https://677719810-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LyjOfAs732TO1n80App%2F-M1of6ZCNANtHTHaqUI3%2F-M1oiRmEN34JZTznr6Ck%2FLogin4.PNG?alt=media\&token=cecae6ff-7fed-4a22-9e7f-f848cc44633a)

Tramite la *Rest Console* accedibile dal menù dei servizi è possibile eseguire le operazioni di creazione, update, cancellazione e listing delle risorse identificate dalle URI ([Uniform Resource Identifier](https://it.wikipedia.org/wiki/Uniform_Resource_Identifier)).

Le risorse dell'applicazione d'esempio che espone un API REST sono:

* <https://gorest.co.in/public/v2/users> per gestire gli utenti;
* <https://gorest.co.in/public/v2/posts> per gestire i post pubblicati;
* <https://gorest.co.in/public/v2/comments> per gestire i commenti pubblicati;
* <https://gorest.co.in/public/v2/todos> per gestire gli impegni;

### RICHIESTE TRAMITE *Postman*

*Postman* è un client per fare richieste a servizi REST, molto utilizzato per fare dei test a servizi che espongono API REST: richieste `GET`, `POST`, `PUT` e `DELETE` tramite una semplice interfaccia grafica.

{% embed url="<https://www.guru99.com/postman-tutorial.html>" %}

Installate *Postman* scaricando il client o utilizzate la versione web del servizio.

Ora facciamo alcune richieste REST al servizio tramite *Postman*:

1. Richiesta elenco degli user - `GET`  <https://gorest.co.in/public/v2/users>
2. Creazione di un nuovo utente - `POST`[ ](https://gorest.co.in/public/v2/users)<https://gorest.co.in/public/v2/users> passando nel body della request i dati dell'utente&#x20;

```json
{
    "name": "Massimo Cappellano",
    "email": "massimo@iisponti.edu.it",
    "gender": "male",
    "status": "active"
}
```

nella response:

```javascript
{
    "id": 6589,
    "name": "Massimo Cappellano",
    "email": "massimo@iisponti.edu.it",
    "gender": "male",
    "status": "active"
}
```

viene ritornato un `id` numerico che identifica in modo univoco l'utente creato. Lo status code della risposta è `201 Created`. **N.B.** Ricordarsi di settare l'header *Authorization* con la propria chiave altrimenti il servizio risponde con messaggio d'errore ("Authorization failed");

3\. Eseguiamo la ricerca dell'elemento - `GET`  [https://gorest.co.in/public/v2/users/](https://gorest.co.in/public/v2/users)[{idUser}](https://gorest.co.in/public-api/users/{ID}) con ID dell'utente prima creato;

4\. Eseguire la cancellazione - `DELETE` [https://gorest.co.in/public/v2/users/](https://gorest.co.in/public/v2/users)[{idUser}](https://gorest.co.in/public-api/users/{ID}) con ID dell'utente prima creato (notate che lo status code della risposta è: `204 No Content`, invece se ripetiamo la richiesta o su una risorsa che non c'è, lo status code della risposta è: `404 Not Found` );

5\. Ripetere l'operazione `GET` dell'utente  [https://gorest.co.in/public/v2/users/{idUser}](https://gorest.co.in/public/v2/users)  per verificare avvenuta cancellazione utente.

**N.B:** Ricordarsi di aggiungere nella richiesta per l'autorizzazione header HTTP`Authorization` con valore `Bearer YOUR-ACCESS-TOKEN`, con valore del proprio *ACCESS TOKEN*:

![Setting Authorization HEADER](https://677719810-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LyjOfAs732TO1n80App%2F-M1qBh_kgBUTf4CTJ49r%2F-M1qYZklI3gqjdx1Luu2%2FAuthorization.PNG?alt=media\&token=ed9e55cd-5f04-4784-a7e9-e8f266a841f0)

### Esempio servizio REST per Gestione Contenuti di un blog

{% embed url="<https://jsonplaceholder.typicode.com/>" %}

Da vedere ad esempio sotto [*Guide*](https://jsonplaceholder.typicode.com/guide/) esempi di chiamate *Nested Routes*:

* <https://jsonplaceholder.typicode.com/posts/1/comments>
* <https://jsonplaceholder.typicode.com/albums/1/photos>
* <https://jsonplaceholder.typicode.com/users/1/albums>
* <https://jsonplaceholder.typicode.com/users/1/todos>
* <https://jsonplaceholder.typicode.com/users/1/posts>

Creazione di un'applicazione per gestire una *ToDo list* prendendo i todo da  <https://jsonplaceholder.typicode.com/>

{% embed url="<https://github.com/checksound/SimpleToDoList>" %}

### Esempio servizio REST per la gestione clienti

<table data-header-hidden><thead><tr><th>Task</th><th width="107">Metodo</th><th>Body</th><th>Path</th></tr></thead><tbody><tr><td><strong>Task</strong></td><td><strong>Metodo</strong></td><td><strong>Body</strong></td><td><strong>Path</strong></td></tr><tr><td>Creazione di un nuovo cliente</td><td><code>POST</code></td><td>JSON</td><td><code>/customers</code></td></tr><tr><td>Cancellazione di un cliente</td><td><code>DELETE</code></td><td>Niente</td><td><code>/customers/{id}</code></td></tr><tr><td>Ritorna un cliente specifico</td><td><code>GET</code></td><td>Niente</td><td><code>/customers/{id}</code></td></tr><tr><td> Ritorna tutti i clienti  </td><td> <code>GET</code></td><td>Niente</td><td> <code>/customers</code></td></tr><tr><td> Modifica uno specifico cliente</td><td><code>PUT</code></td><td>JSON</td><td><code>/customers/{id}</code></td></tr></tbody></table>