GraphQL / Rest (1ère partie)

Nous allons voir dans cette 1ère partie, les similitudes et différences de ces deux technologies et vous montrer que GraphQL est pressenti comme la nouvelle façon de penser une API. GraphQL et REST ne sont pas si différents, mais GraphQL a quelques petits changements qui font une grande différence concernant la vision du développeur de construire et de consommer une API.

Principe de la ressource

Le principal concept de REST est la notion de ressource. Chaque ressource est identifiée par une URL et on récupère cette ressource en envoyant une requête via cette URL. On obtient donc une réponse bien souvent sous la forme JSON selon les besoins.

Voici un exemple :

GET /contacts/1
{
  "civilite": "Monsieur",
  "nom": "Doe",
  "prenom": "John",
  "dateNaissance": "09/11/1980"
  "adresse": { 
    "rue": "61 rue de Bastille",
    "codePostal": "75000",
    "ville": "Paris",
    "pays": "France",
  }
}

Dans l'exemple ci-dessus, nous aurions pu avoir une ressource distincte afin de récupérer l’adresse du contact.

A noter à propos de REST est que le type ou la forme de la ressource et la façon dont on récupére cette ressource sont couplés.

GraphQL est assez différent à cet égard, car pour GraphQL ces deux concepts sont complètement séparés. Dans notre schéma, on pourrait avoir des types Contact et Adresse tels quels :

type Contact {
  id: ID
  civilite : String
  nom: String
  prenom: String
  dateNaissance: Date
  adresse: Adresse
}

type Adresse {
  id: ID
  rue: String
  codePostal: Integer
  ville : String
  pays : String
  contacts: [Contact]
}

Notez que nous avons décrit les types de données disponibles, mais cette description ne nous indique rien sur la façon dont ces objets pourraient être récupérés. C'est une différence fondamentale entre REST et GraphQL, la description d'une ressource particulière n'est pas couplée à la façon dont on la récupére.

Pour pouvoir accéder à un contact ou à une adresse, nous devons créer un type de requête dans notre schéma :

type Query {
  contact(id: ID!): Contact
  adresse(id: ID!): Adresse
}

En comparaison avec Rest, nous aurons à la manière de GraphQL ce type d’appel :

GET /graphql?query={ contact(id: "1") { nom, adresse { codePostal } } }
{
  "nom": "Doe",
  "adresse": {
    "codePostal": "75000",
  }
}

Comme nous pouvons le remarquer, GraphQL  est assez différent de REST, même si l’appel se fait par URL et que la réponse nous est retournée sous la forme JSON.

Dans l’exemple ci dessus, on peut apercevoir dans l'URL via GraphQL que l’on spécifie la ressource demandée et les données voulues.

En d’autres termes même si le contact a comme propriétés civilité, nom, prénom, date de naissance et une adresse composait de la rue, code postal, ville et pays, nous ne demandons en retour que ce qui nous intéresse à savoir dans notre exemple : le contact avec uniquement son nom et pour son adresse le code postal, ainsi les données voulues lors de l’appel correspond aux données en retour.

Cette façon montre le concept de découplage décrit plus haut, nous aurions pu également récupérer le même contact appelée de plusieurs manières avec des propriétés qui nous intéressent :

GET /graphql?query={ contact(id: "1") { nom, prenom, adresse { rue, ville } } }
{
  "nom": "Doe",
  "prenom": "John",
  "adresse": {
    "rue": "75000",
   "ville": "Paris",
  }
}

 

La notion de routes et définition via un schéma pour GraphQL

Lorsque nous consommons une API via n’importe quelle technologie, celle-ci a besoin de savoir ce qui doit être appelé et ce qui est attendu en tant que réponse.

La description lors de la conception d'une API est l’une des choses les plus importantes afin de permettre ce qui peut être accessible comme info. On retrouve bien évidemment cela dans la documentation d’une API.

Dans les API REST d'aujourd'hui, on peut retrouver ce genre d’appel :

GET / contacts /: id
GET / adresses /: id
GET / contacts /: id / telephones
POST / contacts /: id / telephones

On remarque une sorte de "forme" linéaire concernant l’appel d’une API, pour une consultation (GET) ou pour l’enregistrement (POST) nous devrons appeler une url bien spécifique.

En GraphQL, nous n'utilisons pas d'URL pour identifier ce qui est disponible dans l'API. Au lieu de cela, on utilisera le schéma GraphQL:

type Query {
  contact(id: ID!): Contact
  adresse(id: ID!): Adresse
}
type Mutation {
  addTelephone(input: AddTelephoneInput): Telephone
}
type Contact { ... }
type Adresse { ... }
type Telephone { ... }
input AddTelephoneInput { ... }

Dans cet exemple GraphQL fonctionne via une définition par un schéma.

Basiquement ce schéma définit tout ce qui peut être accessibles.

On peut aussi remarquer que ce qui est défini sous le type Query ressemble fortement aux routes définies plus haut. Le type Query est le point d’entrée à nos données.

Voici ce qui différentie en GraphQL par mot clé, une consultation ou modification :

query { ... }
mutation { ... }

Je vous invite pour plus d’informations de consulter la documentation officielle de GraphQL.

Nous irons un peu plus loin avec GraphQL dans une seconde partie.

Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Captcha *

Ce site utilise Akismet pour réduire les indésirables. En savoir plus sur comment les données de vos commentaires sont utilisées.