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
    }
    
  }
}