# API ReST

Una API ReST, nota anche come API RESTful, è un'interfaccia di programmazione delle applicazioni (API o API web) conforme ai vincoli dello stile architetturale ReST, che consente l'interazione con servizi web RESTful. Il termine REST, coniato dall'informatico Roy Fielding, è l'acronimo di REpresentational State Transfer.

La documentazione delle API ReST della piattaforma è pubblicamente disponibile in ogni Ente all'indirizzo:

{% embed url="<https://dominio/PATH/api/docs>" %}
Indirizzo della documentazione delle API
{% endembed %}

Ad esempio per il comune demo della piattaforma è possibile consultarle alla pagina:

{% embed url="<https://servizi.comune.bugliano.pi.it/lang/api/doc>" %}
Documentazione API
{% endembed %}

### Autenticazione

Alcune API richiedono un'autenticazione prima di essere chiamate, in questo caso un cittadino o un operatore possono usare le proprie credenziali per ottenere un token di autenticazione come segue:

## Richiesta token di autenticazione

<mark style="color:green;">`POST`</mark> `https://servizi.comune.bugliano.pi.it/lang/api/auth`

Con questa chiamata si riceve un token di autenticazione in formato JWT, che dovrà essere inviato per tutte le successive chiamate che richiedono autenticazione come *bearer token* nell'header *Autorization*

#### Request Body

| Name                                       | Type   | Description |
| ------------------------------------------ | ------ | ----------- |
| username<mark style="color:red;">\*</mark> | String | nome utente |
| password<mark style="color:red;">\*</mark> | String | password    |

{% tabs %}
{% tab title="200: OK Se le credenziali sono corrette si riceverà un token di autenticazione" %}

{% endtab %}
{% endtabs %}

Alcuni esempi di chiamate

<figure><img src="https://2402436129-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNwAiDeLoMPCkkp1BdSbI%2Fuploads%2FxlRSrIHLVpjttauQ2OH3%2Fimage.png?alt=media&#x26;token=11a487ae-a891-4c7d-8580-4a375cdb8e87" alt=""><figcaption><p>Esempio di chiamata con Postman</p></figcaption></figure>

Esempio di chiamata da linea di comando con il client [Httpie](https://httpie.io/):

```
echo '{ "username": "my-api-user", "password": "xxxx" }' | \
http post https://servizi.comune.bugliano.pi.it/lang/api/auth
```

Esempio di chiamata da linea di comando con il client **curl**:

```
curl \
--header 'Content-Type: application/json' \
--data $'{\n "username": "my-api-user",\n "password": "xxxx"\n}' \
https://servizi.comune.bugliano.pi.it/lang/api/auth 
```

### Versioni delle API

Le API sono disponibili in due versioni, la "**1"** e la "**2"**. Le capacità delle API sono le stesse per le due versioni, nella versione 2 c'e' una migliore gestione del formato JSON, quindi si consiglia l'uso della versione più recente.

È possibile specificare la versione delle Api che si vanno ad interrogare, questo è possibile in 2 modi differenti:

* tramite parametro `version` da passare come parametro delle GET
* tramite parametro `X-Accept-Version` da specificare nell' header della richiesta

La versione di default è per retrocompatibilità la *1*

Dalla versione *2* le chiavi dei valori del campo `data` delle `applications` non sono più restituite come un insieme di strighe piatto separato dal punto (.) ma come campo json con le chiavi esplose.

Nota bene: si raccomanda di specificare sempre la versione di API utilizzata, anche se è il default (1), perche' in futuro il default potrebbe cambiare.