Per semplificare l'utilizzo delle API del SIN2 abbiamo realizzato questa guida, disponibile anche in video su YouTube.
Passo 1: Registrazione
Il primo step necessario per poter cominciare ad utilizzare le API è quello che di registrarsi a questo sito, attraverso il form di registrazione.
Ciò avviene in due fasi: nella prima fase vengono chiesti dei dati e l’accettazione delle condizioni di utilizzo e di privacy.
A questo punto il sistema fornisce un client id da utilizzare per ottenere il token. L’utenza sarà però attiva solo nel momento in cui avremo confermato l’iscrizione cliccando sul link inviato tramite e-mail.
Passo 2: Ottenere il token
Il token è ottenibile con una chiamata all’endpoint:
https://api.turismoattivo.sardegnaturismo.it/oauth/token
La chiamata va effettuata in POST con i seguenti parametri:
- grant_type=password
- scope=ost_editor
- username=<username_scelto>
- password=<password_scelta>
- client_id=<client_id_fornito_in_registrazione>
- client_secret=<identica_alla_password_scelta>
Il sistema risponderà con un json con la seguente struttura:
{
"user_id": 159,
"token_type": "Bearer",
"expires_in": 600000,
"access_token": <token>,
"refresh_token": <refresh_token>
}
L'elemento access_token è quello necessario per effettuare le chiamate. Alla scadenza è necessario richiedere un nuovo token con la stessa chiamata.
Passo 3: Effettuare le chiamate all’endpoint GraphQL
A questo punto siamo pronti per effettuare le chiamate all’endpoint grapqhl, raggiungibile in POST alla URL:
https://api.turismoattivo.sardegnaturismo.it/api/v1.0/graphql
Va aggiunto il token alla chiamata, come header:
Authorization: Bearer <token>
Le chiamate che possiamo effettuare sono:
- queryFestivita: restituisce le festività memorizzate nel sistema
- queryOst: per recuperare gli OST
- querySchedeIntense: per recuperare le schede intense
- queryRegioni: per recuperare le regioni salvate nel sistema
- findOSTById: per recuperare un singolo OST
- findIntenseById: per recuperare una singola scheda intense
Con un tool visuale (ad esempio Insomnia se utilizzate un Mac) è possibile consultare lo schema per visualizzare anche i filtri disponibili e i dati che possiamo recuperare dall’API.
Un esempio di query GraphQL è:
{
queryOst(page: 0, locale: "it", count: 99, geoQuery: {
type: "envelope",
values: [
[9.073333740234377, 40.028666005765274],
[9.986572265625002, 39.71035608240133]
]
})
{
ost {
id
descrizione
name
geometry {
value
}
},
totalCount
}
}