Graphql: un linguaggio di interrogazione per API

GraphQL è un linguaggio di interrogazione lato server per interfacce di programmazione delle applicazioni (API), in grado di fornire ai client unicamente i dati di cui hanno bisogno.

Progettato per rendere le API rapide, flessibili e intuitive per gli sviluppatori, può anche essere distribuito nell'ambiente di sviluppo integrato (IDE) noto come GraphiQL. Nato come alternativa a REST, GraphQL consente agli sviluppatori di ottenere richieste contenenti dati provenienti da più sorgenti, in una singola chiamata API. 

Inoltre, GraphQL offre ai gestori delle API la possibilità di aggiungere o disattivare campi senza influenzare le query esistenti. Gli sviluppatori possono utilizzare qualsiasi metodo per realizzare le API e la specifica di GraphQL garantisce che funzionino in modo prevedibile verso i client.

Gli sviluppatori di API usano GraphQL per creare uno schema in grado di descrivere tutti i possibili dati su cui i client potrebbero eseguire query tramite il servizio specificato. 

Uno schema GraphQL è composto da tipi di oggetto che definiscono la tipologia di oggetti che è possibile richiedere e i tipi di campi disponibili al suo interno. 

Mano a mano che le query vengono ricevute, GraphQL le convalida rispetto allo schema, quindi le esegue.

Lo sviluppatore dell'API aggiunge i campi dello schema a una funzione chiamata resolver. Durante l'esecuzione, il resolver genera il valore.

Oltre a definire e convalidare la sintassi delle query dell'API (indicata nel repository graphql-spec), GraphQL offre notevole flessibilità al progettatore dell'API. GraphQL non fornisce alcuna indicazione su come memorizzare i dati o quale linguaggio di programmazione usare. Gli sviluppatori possono pertanto utilizzare PHP (graphql-php), Scala (Sangria), Python (Graphene Python), Ruby (graphql-ruby), JavaScript (graphql.js) e molti altri. GraphQL non propone requisiti relativi a rete, autorizzazioni o impaginazione.

Dal punto di vista del client, GraphQL si occupa principalmente di query e mutazioni. Se analizzassimo tali operazioni in base al modello CRUD (create, read, update e delete), una query equivarrebbe a read. Tutti gli altri elementi (create, update e delete) vengono gestiti dalle mutazioni.

Se si sta valutando l'adozione di GraphQL in un ambiente aziendale o di livello enterprise, occorre tenere conto dei pro e contro.

I vantaggi di graphql

• Uno schema GraphQL prevede un'unica sorgente di dati in un'applicazione GraphQL. Offre alle organizzazioni la possibilità di eseguire la federazione di tutte le API.
• Le chiamate di GraphQL vengono gestite in un unico percorso di andata/ritorno. I client ricevono solo i dati che hanno richiesto.
• Tipi di dati fortemente definiti riducono gli errori di comunicazione tra il client e il server. 
• GraphQL dispone di funzionalità di introspezione. Un client può richiedere un elenco di tipi di dati disponibili, agevolando la generazione automatica della documentazione.
• GraphQL consente all'API di un'applicazione di evolversi senza interrompere le query esistenti.
• Molte estensioni open source di GraphQL offrono funzionalità non disponibili con le API REST.
• GraphQL non richiede un'architettura applicativa specifica. Può essere introdotto su un'API REST esistente e può lavorare con gli strumenti di gestione delle API.

Gli svantaggi di graphql

• Per gli sviluppatori che sono abituati a interagire con le API REST, GraphQL implica un graduale percorso di apprendimento.
• Spostando molto dell'attività di una query sul lato server, GraphQL rende più onerosi i compiti degli sviluppatori server.
• A seconda del tipo di implementazione, GraphQL potrebbe richiedere diverse strategie di gestione delle API rispetto alle API REST, in particolare se si considerano i limiti di tariffe e prezzi.
• Il caching è molto più complesso rispetto a REST.
• I gestori delle API devono anche scrivere schemi GraphQL di facile manutenzione.

Esempio di query GraphQL

Il modo migliore per capire GraphQL è analizzare da vicino alcune query e risposte. Di seguito prendiamo in esame 3 esempi adattati dal sito web del progetto GraphQL, graphql.org.

Il primo esempio mostra in che modo un client può costruire una query GraphQL, chiedendo a un'API di restituire campi specifici in una determinata forma.

{
  me {
    name
  }
}

Un'API GraphQL restituirebbe un risultato come questo in formato JSON:

{
  "me": {
    "name": "Dorothy"
  }
}

Un client può inoltre includere argomenti in una query GraphQL, come in questo esempio:

{
  human(id: "1000") {
    name
    location
  }
}

Il risultato?

{
  "data": {
    "human": {
      "name": "Dorothy,
      "location": "Kansas"
    }
  }
}

Da questo passaggio in poi, GraphQL offre all'utente più flessibilità, consentendo di definire i frammenti riutilizzabili e di assegnare le variabili desiderate.

Ipotizziamo di dover richiedere un elenco di ID e, successivamente, una serie di record per ogni ID. GraphQL consente di costruire una query in grado di estrarre qualsiasi elemento necessario tramite una sola chiamata API.

Quindi, una query di questo tipo:

query HeroComparison($first: Int = 3) {
  leftComparison: hero(location: KANSAS) {
    ...comparisonFields
  }
  rightComparison: hero(location: OZ) {
    ...comparisonFields
  }
}
fragment comparisonFields on Character {
  name
  friendsConnection(first: $first) {
    totalCount
    edges {
      node {
        name
      }
    }
  }
}

Produrrebbe questo risultato:

{
  "data": {
    "leftComparison": {
      "name": "Dorothy",
      "friendsConnection": {
        "totalCount": 4,
        "edges": [
          {
            "node": {
              "name": "Aunt Em"
            }
          },
          {
            "node": {
              "name": "Uncle Henry"
            }
          },
          {
            "node": {
              "name": "Toto"
            }
          }
        ]
      }
    },
    "rightComparison": {
      "name": "Wizard",
      "friendsConnection": {
        "totalCount": 3,
        "edges": [
          {
            "node": {
              "name": "Scarecrow"
            }
          },
          {
            "node": {
              "name": "Tin Man"
            }
          },
          {
            "node": {
              "name": "Lion"
            }
          }
        ]
      }
    }
  }
}

Se utilizzi GitHub, potrai velocemente acquisire dimestichezza con GraphQL attraverso esperienze pratiche utilizzando lo strumento GraphQL Explorer in GitHub.

GraphQL è stato sviluppato da Facebook, che ha iniziato a utilizzarlo per le applicazioni mobile nel 2012. La specifica di GraphQL è diventata open source nel 2015. È ora supervisionato dalla GraphQL Foundation.

Molti sono i progetti open source che utilizzano GraphQL. L'elenco sottostante non si intende esaustivo, ma include progetti ideati per semplificare l'adozione di GraphQL.

• Apollo, una piattaforma GraphQL che comprende una libreria client frontend (Apollo Client) e un framework del server backend (Apollo Server).
• Offix, un client offline che consente alle mutazioni e alle query GraphQL di essere eseguite anche quando un'applicazione non ha connessione.
• Graphback, un client a riga di comando per la generazione di server Node.js abilitati per GraphQL.
• OpenAPI-to-GraphQL, un'interfaccia a riga di comando e una libreria per rendere in linguaggio GraphQL le API descritte da OpenAPI Specifications o Swagger.