Créer un serveur API GraphQL avec Apollo Server

Vous êtes-vous déjà demandé comment créer une **API** puissante qui permet aux clients de demander exactement ce dont ils ont besoin ? C'est la magie de **GraphQL**, et avec **Apollo Server**, en construire une est plus simple que vous ne l'imaginez ! Si vous en avez assez des points d'accès rigides de REST, **GraphQL** offre de la flexibilité, et **Apollo Server** est l'outil incontournable pour y parvenir. Dans ce tutoriel conversationnel, nous allons vous guider à travers la configuration d'un serveur **GraphQL** en utilisant **Apollo Server**, de l'initialisation du projet au test des requêtes et des mutations. Que vous utilisiez JavaScript ou TypeScript, vous aurez un serveur fonctionnel en un rien de temps. Plongeons-nous et construisons quelque chose de génial avec **GraphQL** et **Apollo Server** !

💡

Vous voulez un excellent outil de test d'API qui génère une belle documentation d'API ?

Vous voulez une plateforme intégrée et tout-en-un pour que votre équipe de développeurs travaille ensemble avec une productivité maximale ?

Apidog répond à toutes vos exigences et remplace Postman à un prix beaucoup plus abordable !

bouton

Pourquoi choisir GraphQL et Apollo Server ?

Avant de retrousser nos manches, parlons de la raison pour laquelle **GraphQL** et **Apollo Server** forment un duo si dynamique. **GraphQL**, développé par Facebook en 2012 et open-sourcé en 2015, est un langage de requête pour les API qui permet aux clients de demander des données spécifiques, réduisant le sur-récupération (over-fetching) et le sous-récupération (under-fetching) courants dans les **API REST**. Au lieu de plusieurs points d'accès, vous avez un point d'accès intelligent qui fournit des réponses personnalisées. C'est efficace, flexible et parfait pour les applications modernes ayant des besoins complexes en données.

Découvrez **Apollo Server**, un serveur **GraphQL** open-source et communautaire d'Apollo GraphQL. Il est prêt pour la production, prend en charge Node.js et s'intègre parfaitement avec des bases de données comme MongoDB ou PostgreSQL. Avec des fonctionnalités telles que le schema stitching, la mise en cache et les abonnements en temps réel, c'est une solution tout-en-un pour la construction d'API évolutives. De plus, il est facile à prendre en main pour les débutants tout en étant puissant pour les professionnels. Comparé à des alternatives comme Express-GraphQL, **Apollo Server** offre une meilleure surveillance des performances et une configuration plus facile. Si vous construisez un blog, un site de commerce électronique ou un backend mobile, cette combinaison vous fera gagner du temps et évitera bien des tracas. Enthousiasmé ? Configurons notre projet !

Configuration de votre projet en JavaScript ou TypeScript

Commençons par créer les bases. Nous allons configurer un projet Node.js et installer les paquets nécessaires. Vous pouvez choisir JavaScript pour la simplicité ou TypeScript pour la sécurité de type – les deux fonctionnent parfaitement avec **Apollo Server**.

Étape 1 : Initialiser le projet

Créer un nouveau dossier :

Ouvrez votre terminal et créez un répertoire de projet :

mkdir graphql-apollo-server
cd graphql-apollo-server

Initialiser Node.js :

Exécutez les commandes suivantes :

npm init -y
npm pkg set type="module"

Ceci crée un fichier package.json pour gérer les dépendances et configure un projet utilisant les modules ES.

Étape 2 : Installer les dépendances

**Apollo Server** nécessite deux paquets principaux : @apollo/server pour le serveur et graphql pour la bibliothèque **GraphQL** de base. Pour TypeScript, nous ajouterons des types et une étape de construction.

Installer les dépendances :

npm install @apollo/server graphql

Pour JavaScript :

Remplacez simplement l'entrée scripts par défaut dans votre fichier package.json par ces entrées type et scripts :

{
	// ...etc.
	"type": "module",
    "scripts": {
    	"start": "node index.js"
    }
    // other dependencies
}

Pour TypeScript (Recommandé) :

1. Initialiser TypeScript :

npm install --save-dev typescript @types/node

Créez un fichier tsconfig.json dans votre répertoire racine et modifiez-le pour inclure :

{
  "compilerOptions": {
    "rootDirs": ["src"],
    "outDir": "dist",
    "lib": ["es2023"],
    "target": "es2023",
    "module": "esnext",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "types": ["node"]
  }
}

2. Enfin, remplacez l'entrée scripts dans votre fichier package.json par les entrées type et scripts suivantes :

{
	// ...etc.
    "type": "module",
    "scripts": {
    	"compile": "tsc",
    	"start": "npm run compile && node ./dist/index.js"
    }
	// other dependencies
}

Conseil de pro : Si vous débutez avec TypeScript, il ajoute la sécurité de type à votre schéma et à vos résolveurs, détectant les erreurs tôt. JavaScript est plus rapide pour les prototypes – choisissez en fonction de l'échelle de votre projet.

Étape 3 : Créer le fichier du serveur

Créez un dossier src à la racine de votre projet et ajoutez un fichier index.ts (ou index.js pour JavaScript) dans le nouveau dossier. C'est là que nous définirons le schéma et les résolveurs.

Tester une requête simple

Construisons notre première requête – un simple message "hello". Cela introduit les définitions de type (schéma) et les résolveurs (fonctions qui récupèrent les données) de **GraphQL**.

Définir le schéma GraphQL

Le schéma est le plan de votre API. Utilisez la balise gql de graphql-tag (incluse avec @apollo/server) pour le définir.

Dans index.ts (ou index.js) :

import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';


// Define GraphQL schema
const typeDefs = `
  type Query {
    hello: String
  }
`;

// Define resolvers
const resolvers = {
  Query: {
    hello: () => "Hello! Welcome to my server",
  },
};

// Create and start the server
const server = new ApolloServer({ typeDefs, resolvers });

const { url } = await startStandaloneServer(server, {
  listen: { port: 4000 },
});

console.log(`🚀  Server ready at: ${url}`);

Pour JavaScript, importez les types :

const { ApolloServer } = '@apollo/server';
const { startStandaloneServer } = '@apollo/server/standalone';

// Rest is the same

Exécuter le serveur

Démarrez votre serveur :

node index.js  # Pour JavaScript
npm start  # Pour TypeScript

Visitez http://localhost:4000 dans votre navigateur. Vous verrez le GraphQL Playground – un IDE basé sur le web pour tester les requêtes.

Tester la requête

Dans le Playground, exécutez cette requête sur le panneau de gauche :

query {
  hello
}

Cliquez sur "Execute". À droite, vous verrez :

{
  "data": {
    "hello": "Hello! Welcome to my server"
  }
}

Succès ! Cette requête simple démontre les bases de **GraphQL** : un type Query avec un champ hello renvoyant une chaîne de caractères. Les résolveurs sont le "cerveau" qui fournit les données – dans ce cas, un message statique. C'est un excellent point de départ pour vérifier votre configuration.

Tester une requête avec un type complexe

Maintenant, ajoutons de la profondeur avec un type personnalisé. Nous allons créer un type Book et une requête pour récupérer une liste de livres. Cela montre comment **GraphQL** gère les données structurées.

Mettre à jour le schéma

Modifiez typeDefs pour inclure un type Book :

const typeDefs = gql`
  type Book {
    title: String
    author: String
  }

  type Query {
    books: [Book]
  }
`;

Ajouter des données d'exemple

Sous les typeDefs, ajoutez les données d'exemple suivantes pour notre nouveau type Book :

// Sample data
const books = [
  {
    title: 'The Awakening',
    author: 'Kate Chopin',
  },
  {
    title: 'City of Glass',
    author: 'Paul Auster',
  },
];

Mettre à jour les résolveurs

Remplacez le contenu du résolveur par ce qui suit pour le type books :

const resolvers = {
  Query: {
    books: () => books
  }
};

Redémarrez le serveur et retournez au Playground.

Tester la requête

Exécutez :

query GetBooks {
  books {
    title
    author
  }
}

Résultat :

{
  "data": {
    "books": [
      {
        "title": "The Awakening",
        "author": "Kate Chopin"
      },
      {
        "title": "City of Glass",
        "author": "Paul Auster"
      }
    ]
  }
}

Cool, n'est-ce pas ? Cette requête récupère un tableau d'objets Book. **GraphQL** permet aux clients de spécifier exactement les champs qu'ils veulent – ni plus, ni moins. Si vous omettez author, il ne renvoie que les titres. Cette flexibilité est la raison pour laquelle **GraphQL** surpasse REST pour les applications gourmandes en données.

Tester une mutation pour ajouter des données

Les requêtes sont pour la lecture, mais les mutations sont pour l'écriture. Ajoutons une mutation pour créer un nouveau livre, démontrant comment **GraphQL** gère la création de données.

Mettre à jour le schéma

Ajoutez un type Mutation :

const typeDefs = `
  type Book {
    title: String
    author: String
  }

  type Query {
    books: [Book]
  }

  type Mutation {
    createBook(title: String!, author: String!): Book
  }
`;

Le ! signifie que les champs sont obligatoires.

Mettre à jour les résolveurs

const resolvers = {
  Query: {
    books: () => books,
  },
  Mutation: {
    createBook: (_: any, { title, author }: { title: string; author: string }) => {
      const newBook = { title, author };
      books.push(newBook);
      return newBook;
    }
  }  
};

Tester la mutation

Dans le Playground, exécutez :

mutation CreateBook{
  createBook(title: "Harry Potter", author: "J.K Rowling") {
    author
    title
  }
}

Résultat :

{
  "data": {
    "createBook": {
      "title": "Harry Potter",
      "author": "J.K Rowling"
    }
  }
}

Pour confirmer, réexécutez la requête GetBooks :

query GetBooks {
  books {
    title
    author
  }
}

Résultat :

{
  "data": {
    "books": [
      {
        "title": "The Awakening",
        "author": "Kate Chopin"
      },
      {
        "title": "City of Glass",
        "author": "Paul Auster"
      },
      {
        "title": "Harry Potter",
        "author": "J.K Rowling"
      }
    ]
  }
}

Le nouveau livre est ajouté ! Les mutations renvoient les données créées, permettant aux clients d'obtenir un retour immédiat. En production, connectez-vous à une base de données comme MongoDB pour la persistance.

JavaScript vs TypeScript : Lequel choisir ? Pour les prototypes rapides, JavaScript est bien – moins de code passe-partout. Mais pour les projets plus importants, TypeScript brille avec la sécurité de type pour les schémas et les résolveurs. TS détecte les erreurs tôt, rendant votre serveur **GraphQL** plus robuste.

Ajouter plus de complexité : ID et requêtes avec arguments

Pour le rendre réel, ajoutez des ID aux livres et une requête pour les récupérer par titre.

Mettre à jour le schéma :

const typeDefs = `
    type Book {
      id: ID!
      title: String
      author: String
    }

    type Query {
      books: [Book]
      book(title: String!): Book
    }

    type Mutation {
      createBook(title: String!, author: String!): Book
    }
`;

Mettre à jour les données et les résolveurs :

// Sample data
const books = [
  {
    id: 1,
    title: 'The Awakening',
    author: 'Kate Chopin',
  },
  {
    id: 2,
    title: 'City of Glass',
    author: 'Paul Auster',
  },
];

// Resolvers 
const resolvers = {
  Query: {
    books: () => books,
    book: (_: any, { title }: { title: string }) => books.find(book => book.title === title),
  },
  Mutation: {
    createBook: (_: any, { title, author }: { title: string; author: string }) => {
      const newBook = { id: books.length + 1, title, author };
      books.push(newBook);
      return newBook;
    }
  }  
};

Tester la requête :

query GetBook {
  book(title: "The Awakening") {
    id
    title
    author
  }
}

Résultat :

{
  "data": {
    "book": {
      "id": "1",
      "title": "The Awakening",
      "author": "Kate Chopin"
    }
  }
}

Ceci montre les arguments dans les requêtes, permettant aux clients de filtrer les données efficacement.

Bonnes pratiques pour GraphQL avec Apollo Server

Conception du schéma : Gardez-le modulaire avec plusieurs fichiers.
Gestion des erreurs : Utilisez ApolloError pour les erreurs personnalisées.
Performance : Activez la mise en cache avec @apollo/cache-control.
Abonnements : Ajoutez le temps réel avec apollo-server-express.
Surveillance : Utilisez Apollo Studio pour les métriques.

Dépannage des problèmes courants

Le serveur ne démarre pas ? Vérifiez la version de Node (14+) et les dépendances.
Erreurs de requête ? Vérifiez la correspondance schéma/résolveur.
Problèmes CORS ? Ajoutez { cors: { origin: '*' } } aux options du serveur.
Erreurs TS ? Installez @types/graphql et @types/node.

Conclusion

Nous avons construit un serveur **GraphQL** robuste avec **Apollo Server**, des requêtes "hello" aux mutations. Que ce soit en JS ou en TS, vous êtes prêt à créer des API flexibles. Expérimentez, ajoutez des abonnements et déployez sur Heroku. **GraphQL** et **Apollo Server** sont votre passeport pour des API efficaces !

Apidog prend également en charge les tests avec GraphQL, alors assurez-vous de le découvrir complètement **GRATUIT** !

bouton