API REST vs GraphQL : Différences et similarités

Les APIs sont devenues une partie intégrante du développement d’applications modernes. Elles permettent à deux applications ou plus de communiquer entre elles et d’échanger des données.

Dans cet article, nous allons comparer deux types d’APIs populaires : les APIs REST et les APIs GraphQL. Nous examinerons leurs différences et leurs similitudes, et nous verrons les critères sur lesquels nous pouvons se baser pour choisir le bon type d’APIs pour nos applications.

API REST

Les API REST sont basées sur le modèle architectural REST (Representational State Transfer). Elles utilisent des URIs pour identifier des ressources, et des verbes HTTP pour effectuer des opérations sur ces ressources (GET, POST, PUT, PATCH, DELETE…).

Supposons que nous ayons une API REST pour une application de commerce électronique.

L’URI /products représenterait la collection de tous les produits disponibles. La méthode GET sur cette URI renverrait une liste de tous les produits, sous la forme d'un tableau JSON.

Pour obtenir des informations sur un produit spécifique, nous pourrions utiliser l’URI /products/{id}, où {id} est l'identifiant du produit. La méthode GET sur cette URI renverrait les données du produit correspondant.

Avantages

• Bien établies et largement utilisées
• Relativement faciles à comprendre et à mettre en œuvre
• Compatibles avec de nombreux langages de programmation et frameworks
• Integration facile avec les apim
• Opérations Rest cachables (cache) par défaut

Inconvénients

• Moins efficaces pour les requêtes complexes.
• Peuvent nécessiter plusieurs requêtes pour récupérer des données associées ou imbriquées.

API GraphQL

Les API GraphQL sont basées sur un langage de requêtes dédié. Elles permettent aux clients de demander exactement les données dont ils ont besoin.

Supposons que nous ayons une API GraphQL pour une application de commerce électronique. La requête suivante renverrait la liste de tous les produits, leur noms et catégories ainsi que le nombre de produits dans la catégorie “Electroménager" par exemple :

query {
	products {
		name
		category
	}
	countProductsByCategory(category: "Électroménager")
}

qui aura comme résultat dans graphql :

{
  "data": {
    "products": [
      {
        "name": "Laptop",
        "category": "Electronics"
      },
      {
        "name": "Smartphone",
        "category": "Electronics"
      },
      {
        "name": "Headphones",
        "category": "Electronics"
      },
      {
        "name": "Blender",
        "category": "Electroménager"
      },
      {
        "name": "Washing Machine",
        "category": "Electroménager"
      }
    ],
    "countProductsByCategory": 2
  }
}

Nous pouvons même ajouter des champs calculés dans les réponses aux queries comme vous pouvez le voir dans le champs "countProductsByCategory" qui donne en entrée une catégorie et calcule le nombre de produits attachés à cette catégorie.

countProductsByCategory: ({ category }) => products.filter(product => product.category === category).length

Avantages

• Plus efficaces pour les requêtes complexes.
• Permettent de récupérer des données associées ou imbriquées en un seul appel ce qui est peut être très utiles pour une logique de consommation de données.
• Plus flexibles que les API REST.

Inconvénients

• Moins bien établies que les API REST
• Peuvent être plus difficiles à comprendre et à mettre en œuvre

Différences entre API Rest et GraphQl

La principale différence entre les APIs REST et les APIs GraphQL est la façon dont ils gèrent les données. Les APIs REST renvoient généralement un ensemble de données complet, même si le client n’en a besoin que d’une partie ce qui peut être util dans certains scénarios. Les APIs GraphQL, en revanche, renvoient uniquement les données qui ont été demandées par le client. Cette différence peut avoir un impact significatif sur les performances des applications. Les APIs REST peuvent être moins efficaces pour les requêtes complexes.

Par exemple si on veut récupérer le prix du produit qui a la valeur de son id égale à 1 (id=1) avec une api Rest, le résultat sera le suivant :

{
      "id": "1",
      "description": "Powerful laptop with high-performance specifications.",
      "name": "Laptop",
      "price": 999.99,
      "category": "Electronics"
}

en utilisant l’endpoint /products/1 l’api Rest ici nous renvoie toutes les informations sur le produit tandis que nous voulons juste récupérer son prix.

Dans ce cas, Si nous souhaitons modifier l’API REST pour ne renvoyer que le prix d’un produit au lieu de toutes ses informations, nous pourrions envisager de créer une nouvelle route ou de modifier la route existante pour accepter un paramètre de requête indiquant que seul le prix doit être renvoyé.

Par exemple avec cet url /products/1/price nous pouvons récupérer le prix :

{
  "price": 999.99
}

Avec une api graphql, nous pouvons préciser que nous voulons récupérer juste le prix et pas d’autres information à travers la même query :

query {
 getProduct(id:1) {
    price
 }
}

Et nous aurons comme résultat :

{
  "data": {
    "getProduct": {
      "price": 999.99
    }
  }
}

Les approches des API REST et GraphQL diffèrent dans la façon dont elles gèrent les requêtes. Les APIs REST utilisent des URI pour identifier les ressources, tandis que les APIs GraphQL utilisent un langage de requêtes dédié, appelé queries, et toutes les requêtes sont dirigées vers un seul endpoint /graphql.

Supposons que nous voulons avoir les détails de tous les produits de la commande numéro 89.

Dans une api Rest traditionnelle, nous allons probablement faire appel à deux endpoints différents pour accomplir cela. Nous ferons d’abord un appel à /orders/89 pour récupérer la commande 89 qui contient les ids des produits la composant puis nous ferons un autre appel avec les ids de ces produit pour avoir leur détails avec l’endpoint /products?ids=[1,2...].

Ceci peut être une manipulation lourde et chronophage côté serveur surtout si la commande contient un nombre important de produits.

En revanche, avec GraphQL, la manipulation de ces données devient plus simple. Il suffit de rédiger une seule query avec des champs imbriqués pour obtenir toutes les informations nécessaires en un seul appel au serveur, comme illustré ci-dessous :

{
  getOrder(id: "89") {
    id
    totalPrice
    products {
      id
      name
      price
    }
  }
}

Comme vous pouvez le voir, graphql supporte les champs imbriqués dans une query.
Nous aurons comme réponse à notre query l’objet json suivant :

{
  "data": {
    "getOrder": {
      "id": "1",
      "totalPrice": 1149.98,
      "products": [
        {
          "id": "1",
          "name": "Laptop",
          "price": 999.99
        },
        {
          "id": "3",
          "name": "Headphones",
          "price": 149.99
        }
      ]
    }
  }
}

GraphQL gère la mise en cache d’une manière complètement différente d’une API REST, principalement parce que les requêtes GraphQL ne sont pas strictement basées sur la spécification HTTP. Dans une requête GraphQL typique, chaque requête est un POST et il n’y a aucun concept de GET, PUT ou DELETE. Par conséquent, il s’appuie sur une identification unique des objets côté client pour le comportement de mise en cache.

La gestion des erreurs est un autre point de différence entre les deux types d’api. Contrairement aux apis Rest, Graphql n’est pas en mesure de retourner les codes d’erreurs utilisés par le protocole HTTP. Par exemple, on peut avoir une erreur dans la réponse envoyée par le serveur mais on a toujours un 200 OK comme code côté client. Graphql utilise plutôt des objets erreur dans la réponse pour identifier les erreurs. Ce qui rend l’observabilité des erreurs difficile sur les apim comme gravitee par exemple.

Nous essayons par exemple d’appeler le champ toto dans getProduct qui n’existe pas par la query suivante :

{
  getProduct(id: "1") {
    id
    toto
  }
}

Le code d’erreur reçu côté client est toujours 200 OK mais le message d’erreur est précis dans ce cas :

{
  "errors": [
    {
      "message": "Cannot query field \"toto\" on type \"Product\".",
      "locations": [
        {
          "line": 4,
          "column": 5
        }
      ]
    }
  ]
}

Similarités

Les APIs REST et les APIs GraphQL présentent également des similitudes. Elles utilisent toutes deux le protocole HTTP pour communiquer avec les serveurs. Elles utilisent également des librairies et des frameworks pour gérer les détails du réseau et des protocoles. Elles représentent deux choix viables pour les applications modernes.

Conclusion

En résumé, le choix entre une API REST et GraphQL dépend étroitement des exigences spécifiques de votre application. Si la simplicité et la facilité de compréhension sont des critères essentiels, une API REST peut être une option judicieuse. D’autre part, si votre application nécessite des requêtes complexes et une flexibilité dans la récupération des données, GraphQL peut offrir une solution plus efficace. En examinant nos exemples, une API GraphQL permet une récupération précise des données, par exemple en obtenant le prix d’un produit spécifique ou en récupérant une commande avec des produits imbriqués. Il est donc crucial de prendre en compte la nature et la complexité des opérations que votre application devra effectuer pour faire un choix éclairé entre ces deux technologies.

Un article de Faten Maalem