Prima di scrivere il nostro primo servizio con GraphQL è necessario prendere confidenza con alcuni concetti di base. Sarà necessario, in primis, saper:

• definire aggregazioni di dati per stabilire le tipologie di informazioni che verranno trattate;
• indicare le query che potranno essere inoltrate al servizio per recuperare informazioni;
• specificare le manipolazioni che dovranno essere permesse dal servizio per la modifica dei dati.

Al centro di tutto ciò si colloca il sistema di tipi di dato disponibili in GraphQL.

Tipi di dato fondamentali

GraphQL definisce alcuni tipi di dato fondamentali che permettono di descrivere ogni tipologia di informazione di base. L’aggregazione di più variabili basate su tali tipi di dato darà vita a degli oggetti. Eccone un elenco:

• String: stringhe in senso classico, ovvero sequenze alfanumeriche di caratteri espresse con codifica UTF-8;
• Int: interi a 32 bit con segno;
• Float: numeri in virgola a doppia precisione, anche questi con segno;
• Bool: valori logici booleani che possono valere True o False;
• ID: identificatore univoco, serializzato come stringa, che permette di identificare le informazioni nel servizio.

Si può inoltre specificare un array circondando un tipo di dato con parentesi quadre e stabilire che un dato non possa essere nullo facendone seguire il tipo con un punto esclamativo. Si possono specificare informazioni di più alto livello usando il costrutto type, un pò come se creassimo classi nella programmazione a oggetti. Vediamo un esempio subito:

type Persona {
  nome: String
  cognome: String!
  eta: Int
  citta: String
}

In questo caso, il tipo Persona sarà composto da quattro campi: un nome, un cognome, un’età ed una città, di cui i primi due ed il quarto di tipo String, ed il terzo Int. Con il punto esclamativo abbiamo sottolineato l’impossibilità che il campo cognome sia nullo.

Gli oggetti possono poi essere aggregati in ulteriori tipologie; vediamo un altro esempio:

type CorsoFormazione {
  titolo: String
  allievi: [Persona]
}

Il tipo CorsoFormazione sarà costituito da un campo titolo di tipo String e da una classe di allievi i cui dati saranno raccolti in un array di oggetti Persona.

Query e Mutation

Query e Mutation sono quegli elementi che in GraphQL sopperiscono al ruolo che i metodi HTTP hanno in REST. Le Query costituiscono l’equivalente di una GET HTTP (operazioni idempotenti per la lettura dei dati) mentre le Mutation rappresentano ogni tipo di manipolazione dei dati, corrispondendo all’uso che su REST si fa dei metodi HTTP POST, PUT e DELETE. Un tipo Query può essere definito così:

type Query {
  numeroPersone: Int
  elencoPersone: [Persona]
}

Abbiamo specificato due interrogazioni: una che restituisce il numero di persone, e l’altra che offre un elenco delle persone disponibili.

Con le Mutation definiamo operazioni destinate a cambiare il set di dati a disposizione del servizio. Ad esempio:

type Mutation {
  creaPersona(nome: String, cognome: String): Persona
}

In questo caso, è stato definito un tipo di mutazione che riceve in input due argomenti – nome e cognome, entrambi di tipo String – e li usa per fondare un’informazione di tipo Persona che costituirà altresì il risultato della mutazione.

Ricapitolando, il percorso per la definizione di un servizio GraphQL si muove per lo più lungo questi filoni:

• definizione dei tipi di informazione fondamentali del servizio sfruttando i dati scalari di base;
• pianificazione delle attività di query possibili e dei relativi parametri di accesso nonchè del tipo di ritorno;
• specifica delle varie tipologie di mutazione per la modifica del set di dati a disposizione del server.

Tutto ciò completa la fase di definizione dei tipi che sarà seguita dalla specifica dei resolver, le implementazioni delle funzionalità offerte dal servizio. Tutti questi elementi verranno presto sfruttati nel corso della guida per la definizione di un servizio di prova.