Gérez efficacement votre API GraphQL avec API Gateway

GraphQL est un langage de requête pour les API puissant qui permet aux développeurs de définir la structure des données dont ils ont besoin depuis le serveur, et le serveur répond uniquement avec ces données. Cela le rend beaucoup plus efficace et flexible que les API REST traditionnelles, qui nécessitent souvent plusieurs requêtes pour récupérer les mêmes données. Cependant, la gestion des API GraphQL peut être complexe et chronophage, surtout à grande échelle. C'est là qu'une Passerelle API entre en jeu.

L'une des fonctionnalités clés des passerelles API modernes comme Apache APISIX est son support pour les API GraphQL. APISIX facilite la gestion et la mise à l'échelle des API GraphQL grâce à son système de configuration flexible et à ses puissants plugins. L'un de ces plugins est le plugin degrapghql, qui permet de convertir une API GraphQL en une API REST. Dans cet article, nous explorerons cette fonctionnalité avec un exemple.

Objectifs d'apprentissage

Vous apprendrez et trouverez des réponses aux questions suivantes tout au long de l'article :

Qu'est-ce que le plugin DeGraphQL ?
Quels sont les cas d'utilisation et les fonctionnalités du plugin DeGraphQL ?
Comment utiliser le plugin DeGraphQL.
Comment transformer REST en GraphQL ?
Comment gérer le trafic des API GraphQL ?

Gérez votre API GraphQL avec une passerelle API

Pourquoi utiliser le plugin DeGraphQL ?

Ce plugin est capable de transformer les API exposées par un service backend GraphQL en un point de terminaison REST traditionnel en mappant les URI sur des requêtes GraphQL. Appeler des API REST depuis un client typique ouvre les avantages de GraphQL à plus de personnes, considérez les cas d'utilisation suivants :

Cas d'utilisation 1 : Vos clients existants sont habitués à consommer des API REST et ne sont pas trop familiers avec l'écriture de requêtes GraphQL. Pour leur simplifier la tâche, vous pouvez utiliser la passerelle API Apache APISIX pour convertir une API GraphQL en une API REST.

Cas d'utilisation 2 : Vous faites partie d'une équipe de développement front-end qui souhaite essayer les fonctionnalités existantes d'une API GraphQL sans demander à l'équipe back-end de mettre en place un nouveau serveur GraphQL.

Cas d'utilisation 3 : Vous n'avez pas accès pour modifier le backend car il s'agit d'un ensemble existant d'API GraphQL, potentiellement géré par un tiers.

Cas d'utilisation 4 : Vous avez une infrastructure d'API REST existante, mais vous souhaitez évaluer si GraphQL peut répondre à vos besoins.

Cas d'utilisation 5 : Vous avez une base de code importante, et la migration vers GraphQL est en cours côté backend, mais vous souhaitez utiliser GraphQL maintenant sans attendre.

Cas d'utilisation 6 : Vous avez plusieurs microservices qui utilisent une combinaison des deux approches. Vous souhaitez permettre une communication fluide entre eux.

Quelles sont les fonctionnalités du plugin DeGraphQL ?

Le plugin DeGraphQL offre un certain nombre de fonctionnalités utiles qui facilitent la configuration et la gestion de votre API GraphQL, notamment :

Validation des requêtes : Il peut valider les requêtes GraphQL entrantes pour s'assurer qu'elles répondent à certains critères. Cela peut inclure la vérification de la structure de la requête, l'application de contraintes sur les types d'entrée, et plus encore. En validant les requêtes, vous pouvez vous assurer que votre API reçoit toujours des requêtes valides et bien formées.

Analyse des requêtes : Il peut également analyser les requêtes GraphQL, vous permettant d'extraire des informations spécifiques de la requête et de les utiliser pour influencer le comportement de votre API. Cela peut inclure des choses comme la sélection du service backend approprié en fonction des données demandées, ou la modification de la réponse en fonction de certains paramètres de la requête.

Transformation des réponses : Enfin, il peut transformer les réponses GraphQL avant qu'elles ne soient renvoyées au client. Cela peut être utile pour des choses comme la normalisation des structures de données, la suppression d'informations sensibles, ou l'ajout de données supplémentaires à la réponse.

Avec cette capacité, Apache APISIX non seulement facilite l'utilisation conjointe de REST et GraphQL, mais vous permet également de définir des limites de débit, d'appliquer l'authentification et l'autorisation, de bloquer les clients qui tentent d'utiliser une API de manière abusive, et de s'assurer que les API fonctionnent de manière transparente lors de leurs mises à jour avec l'aide d'autres plugins intégrés.

Comment utiliser le plugin DeGraphQL (Démonstration)

Avec suffisamment de connaissances théoriques en tête, nous pouvons maintenant passer à une démonstration pratique du plugin DeGraphQL. DeGraphQL a besoin d'un point de terminaison GraphQL pour interroger. À titre d'exemple, nous allons utiliser l'une des API GraphQL publiques gratuites qui récupèrent des informations sur les pays, les continents et les langues https://countries.trevorblades.com/.

Si vous naviguez vers le lien de l'API Countries ci-dessus, cela ouvrira un terrain de jeu où vous pouvez écrire des requêtes contre l'API GraphQL via l'interface utilisateur.

Interrogation d'une API GraphQL

Vous pouvez également créer votre propre API GraphQL en utilisant StepZen ou ApollographQL qui fournissent des studios GraphQL vous aidant à construire et déployer votre propre API GraphQL en combinant des API préconstruites telles que Accuweather, Airtable, GitHub, Twitter, Trello, et plus encore. Par exemple, vous pouvez composer deux API Accuteweather et Countries ensemble pour collecter les informations météorologiques fournies par un nom de pays/ville et placer APISIX en avant pour interroger l'API depuis REST.

Notre tâche consiste maintenant à transformer la définition de requête ci-dessus en un simple appel REST et à l'envoyer sous forme de données JSON. En conséquence, la passerelle API Apache APISIX expose le point de terminaison REST et devrait être capable de router toutes les requêtes vers l'API GraphQL.

Par exemple, toutes les requêtes REST vers le chemin d'URI /country-info de la passerelle API avec une requête sous-jacente par un code de pays devraient être converties et transmises à l'API GraphQL Countries https://countries.trevorblades.com/graphql.

Un exemple de commande curl ressemblerait à ceci :

curl -i http://127.0.0.1:9080/country-info  -X POST -d \
'{
   "code": "EE"
}'

Et nous devrions obtenir une réponse de l'API comme suit :

{
  "data": {
    "country": {
      "code": "EE",
      "capital": "Tallinn",
      "currency": "EUR",
      "languages": [
        {
          "name": "Estonian"
        }
      ]
    }
  }
}

Dans les sections suivantes, nous apprendrons comment y parvenir étape par étape.

Mettons Apache APISIX en marche

Avant de pouvoir utiliser le plugin degrapghql, vous devez installer Apache APISIX. Vous pouvez suivre les instructions d'installation sur le site web d'Apache APISIX pour commencer.

Prérequis

Docker est utilisé pour installer etcd et APISIX conteneurisés.
curl est utilisé pour envoyer des requêtes à APISIX pour validation. Vous pouvez également utiliser des outils simples comme Postman pour interagir avec l'API.

APISIX peut être facilement installé et démarré avec le script de démarrage rapide suivant :

curl -sL https://run.api7.ai/apisix/quickstart | sh

Cela créera deux conteneurs Docker – un etcd pour stocker la configuration et la passerelle APISIX elle-même. Une fois que vous voyez le message “✔ APISIX est prêt !”, nous pouvons configurer un upstream, un plugin et une route via l'API Admin d'APISIX qui proxy les requêtes vers l'API GraphQL.

Créer un Upstream

Ensuite, nous allons créer un objet Upstream pour enregistrer notre API GraphQL Countries dans la passerelle API :

curl "http://127.0.0.1:9180/apisix/admin/upstreams/1" -X PUT -d '
{
  "name": "GraphQL API upstream",
  "desc": "Enregistrer l'API GraphQL Countries comme upstream",
  "type": "roundrobin",
  "scheme": "https",
  "nodes": {
    "countries.trevorblades.com": 1
  }
}'

Créer une configuration de plugin

Ensuite, nous allons configurer un nouvel objet plugin config. Nous utiliserons deux plugins de transformation proxy-rewrite et degraphql pour réécrire l'hôte et l'URI de la requête et effectuer une requête à l'API GraphQL respectivement.

curl http://127.0.0.1:9180/apisix/admin/plugin_configs/1 -X PUT -d '
{
   "plugins":{
      "proxy-rewrite":{
         "uri":"/graphql",
         "host":"countries.trevorblades.com"
      },
      "degraphql":{
         "query":"query Country($code: ID!) {
                country(code: $code) {
                    code
                    capital
                    currency
                    languages {
                        name
                    }
                }  
          }",
         "variables":[
            "code"
         ]
      }
   }
}'

Dans la configuration du plugin DeGraphQL ci-dessus, nous avons défini deux attributs tels que query et variables. Les variables de requête GraphQL peuvent être définies dans le corps de la requête POST ou dans les URI d'un appel REST.

La requête que nous exécutons, dans ce cas, ressemble à ce qui suit et vous pouvez la remplacer par la vôtre :

query ($code: ID!) {
  country(code: $code) {
    code
    capital
    currency
    languages {
      name
    }
  }
}

Créer une route avec le plugin DeGraphQL

Cette étape consiste à configurer une nouvelle route qui utilise la configuration de plugin, et à configurer la route pour qu'elle fonctionne avec l'upstream (en référençant leurs ID) que nous avons créé dans les étapes précédentes :

curl -i http://127.0.0.1:9180/apisix/admin/routes/1 -X PUT -d '
{
   "name":"GraphQL API route",
   "desc":"Créer une nouvelle route dans APISIX pour l'API GraphQL Countries",
   "uri":"/country-info",
   "upstream_id":"1",
   "plugin_config_id":1
}'

Tester l'activation du plugin DeGraphQL

Maintenant, testons cette nouvelle configuration avec la commande curl suivante.

curl -i http://127.0.0.1:9080/country-info  -X POST -d \
'{
   "code": "EE"
}'

Nous obtiendrons une réponse d'APISIX :

{
  "data": {
    "country": {
      "code": "EE",
      "capital": "Tallinn",
      "currency": "EUR",
      "languages": [
        {
          "name": "Estonian"
        }
      ]
    }
  }
}

La même variable code peut également être fournie comme arguments GET :

curl -i http://127.0.0.1:9080/country-info?code=EE

Transformation des réponses

Avec l'aide du plugin response-rewrite d'Apisix, il est possible de transformer les réponses GraphQL avant qu'elles ne soient renvoyées au client. Utilisons ce plugin pour supprimer la clé currency et sa valeur de la réponse JSON pour ne montrer que tout le reste. Pour ce faire, nous devons ajouter le plugin response-rewrite à la configuration de plugin existante.

curl http://127.0.0.1:9180/apisix/admin/plugin_configs/1 -X PATCH -d '
{
  "plugins":{
   "response-rewrite": {
      "filters":[
        {
          "regex":"(?:\"currency\":\")(.*?)(?:\")",
          "scope":"once",
          "replace":""
        }
      ],
      "vars":[
        [
          "status",
          "==",
          200
        ]
      ]
   }
  }
}'

Après l'installation de ce plugin, vous pouvez faire une requête à /country-info une fois de plus et voir la réponse transformée :

{
  "data": {
    "country": {
      "code": "EE",
      "capital": "Tallinn",
      "languages": [
        {
          "name": "Estonian"
        }
      ]
    }
  }
}

Résumé

Globalement, le plugin DeGraphQL est un outil essentiel pour tout développeur construisant une API GraphQL avec APISIX. Ses fonctionnalités puissantes et sa configuration facile à utiliser en font un jeu d'enfant à intégrer dans votre passerelle API existante, tandis que son support pour les fonctionnalités spécifiques à GraphQL garantit que votre API est performante, fiable et évolutive.