Le API del SIN2

Il SIN2 espone un endpoint GraphQL per interrogare e recuperare i dati geografici da esso gestiti, in particolare gli OST e le Schede Intense presenti nel sistema.

In particolare ci sono 4 tipologie di query accessibili via GraphQL:

queryOst(fulltext, filters, geoQuery, page ,count, exclude, include, locale, order, orderby, last_modified_since): SearchResults
querySchedeIntense(fulltext, filters, geoQuery, page ,count, include, locale, order, orderby, last_modified_since): SearchResults
findOSTById(id: Int, locale: string): OST
findIntenseById(id: Int, locale: string): Intense

I primi due endpoint consentono di effettuare le ricerche su OST e sulle Schede Intense. mentre i restanti due recuperano esattamente una Scheda Intense o un OST a partire dal loro ID (restituito in fase di search).

Autenticazione

L’accesso all’endpoint GraphQL è possibile solo dopo essersi autenticati mediante il protocollo OAUTH2. Di seguito i dettagli:

OAuth2 Token API → Access Token e Refresh Token

Endpoint: /oauth/token

Autenticazione: Consumer/Drupal username-password

Method: POST

Header: Content-type → multipart/form-data

Form data:

grant_type → password
client_id → {consumer id}
client_secret → {consumer secret}
username → {Drupal username}
password → {Drupal user password}
scope → ost_editor

Response (JSON Object):

token_type → Bearer
expires_in → {secondi scadenza token}
access_token → {token accesso}
refresh_token → {token per rinnovo token accesso}

Descrizione utilizzo OAuth2 Refresh Token:

https://oauth2.thephpleague.com/authorization-server/refresh-token-grant/

Il servizio GraphQL

L’endpoint di GraphQL consente di trovare OST, Schede Intense e regioni storiche presenti nel sistema.

Lo schema GraphQL utilizzato può essere visionato nel documento qui disponibile.

Nello schema è mostrato il formato delle query e delle risposte. E' possibile svolgere 6 tipi di query:

querySchedeIntense. Ricerca le schede Intense con la possibilità di applicare filtri.
queryOst. Ricerca di OST con la possibilità di applicare filtri.
queryFestivita. Restituisce tutte le festività definite nel sistema.
queryRegioni. Restituisce le regioni storiche della Sardegna
findOSTById. Ricerca degli OST tramite id.
findIntenseById. Ricerca delle schede Intense tramite id.

Le prime due query sono solitamente invocate con una serie di argomenti:

orderBy. Imposta il campo in cui effettuare l’ordinamento
order. Imposta il tipo di ordinamento: ascendente o discendente.
type. Presente solamente nella ricerca di OST. Indica il tipo di OST da ricercare. I possibili valori sono: ost_sentiero_percorso, ost_attrattore, ost_servizi, ost_waypoint
fulltext. Indica la stringa di ricerca.
facets. Indica le facets da restituire nella risposta.
filters. Indica il filtro da applicare alla ricerca. La definizione del filtro dipende alle facets esistenti.
count. Imposta numero di risultati per pagina.
page. Imposta il numero di pagina
geoQuery. Imposta un filtro geo-spaziale.
last_modified_since. Filtra i risultati in base alla data di ultima modifica.

Esempi di query GraphQL

Ricerca Schede Intense

{
  querySchedeIntense(page: 0, locale: "it", count: 10, geoQuery: {
     type: "envelope",
    values: [
        [9.073333740234377, 40.028666005765274],
         [9.986572265625002, 39.71035608240133]
    ]
   })
  {
    schedeIntense {
      id
      descrizione
      name
      difficolta {
      name
      }
      geometry {
      value
      }
    },
    totalCount
  }
}

RicercaOST

{
  queryOst(page: 1, type: "ost_sentiero_percorso", locale: "it", count: 99, geoQuery: {
     type: "envelope",
    values: [
         [9.073333740234377, 40.028666005765274],
         [9.986572265625002, 39.71035608240133]
    ]
   })
  {
    ost {
      id
      descrizione
      name
      geometry {
      value
      }
    },
    totalCount
  }
}

Ricerca Schede Intense per ID

{
  findIntenseById(id: 4360, locale: "it")
  {
    
    id
    name
    difficolta {
      name
    }
    
  }
}