Partie 2 : le schéma dans GraphQL

Journal de bord du capitaine, jour 2 sur l’île de GraphQL :

Musique de fond pour l'article

Rôle du schéma GraphQL

Aujourd'hui, nous abordons une pierre angulaire de notre expédition : le schéma GraphQL.
Cet artefact précieux établit les règles du jeu entre le client et le serveur, agissant tel un contrat qui fixe :

les types de données
les opérations permises
les règles de validation.

Grâce à ce schéma, chaque membre de l’équipage sait exactement quelles données sont accessibles et comment les manier.

Pourquoi ce schéma est-il notre trésor ?

Les richesses du schéma sont nombreuses et précieuses :

Documentation vivante : nul besoin de parchemins compliqués ; le schéma lui-même sert de carte, guidant tout explorateur à travers les routes des données disponibles.
Validation et sécurité : ce schéma impose des contraintes de type et de structure, rendant les requêtes aussi sûres qu’un coffre fermé par sept serrures.
Autonomie des développeurs : chaque membre d’équipage peut, en toute indépendance, explorer et assembler les requêtes dont il a besoin.
Réduction des erreurs : en forçant une structure et des types précis, le schéma réduit les risques d’erreurs et maintient l’ordre parmi les données.

Un seul schéma pour garder la mer calme

Certains pourraient être tentés de diviser leurs trésors en plusieurs schémas. Mais gare !
Cela augmente la complexité et crée des fragments où certaines données seraient isolées, rendant la navigation périlleuse. Pour garder une API claire et maîtrisable, un seul schéma est bien plus sage.

Notre schéma à nous, capitaine !

Pour notre aventure, nous avons placé le schéma dans un fichier .graphqls au cœur de notre embarcation, dans le répertoire src/main/resources/graphql/. Ce parchemin y spécifie chaque type, requête et mutation qui constitue notre API. Voici les trésors principaux définis dans notre schéma :

type Author {
    id: ID!
    name: String!
    bio: String
    articles: [Article]
}

type Article {
    id: ID!
    title: String!
    content: String!
    author: Author!
}

type Query {
    getAuthors: [Author]
    getAuthorById(id: ID!): Author
    getArticles: [Article]
    getArticleById(id: ID!): Article
}

type Mutation {
    createAuthor(name: String!, bio: String): Author
    createArticle(title: String!, content: String!, authorId: ID!): Article
}

schéma graphql

Query : c’est notre longue-vue pour observer le monde sans le modifier, comme l’opération GET dans les API REST.
Mutation : l’équivalent des opérations POST, PUT, et DELETE de REST, Mutation est notre hache pour créer ou modifier le contenu de notre trésor.

Le symbole du point d'exclamation !

Lorsqu’on voit un ! dans notre schéma, cela signifie que le type est non-nul, comme une règle gravée dans le bois du navire.
Cela impose une valeur obligatoire pour ce champ, garantissant ainsi des requêtes sûres et sans surprise.

Fin de l’entrée. Prochaine étape : mettons en œuvre ces trésors et préparons-nous à exposer nos données via des controllers