Un guide du débutant sur GraphQL

L'un des termes les plus couramment discutés aujourd'hui est l'API. Beaucoup de gens ne savent pas exactement ce qu'est une API. Fondamentalement, API signifie Interface de programmation d'application. Il s'agit, comme son nom l'indique, d'une interface avec laquelle les personnes - développeurs, utilisateurs, consommateurs - peuvent interagir avec les données.

Vous pouvez considérer une API comme un barman. Vous demandez au barman de boire un verre et ils vous donnent ce que vous vouliez. Facile. Alors pourquoi est-ce un problème?

Depuis le début du Web moderne, créer des API n'a pas été aussi difficile qu'il y paraît. Mais l'apprentissage et la compréhension des API l'étaient. Les développeurs forment la majorité des personnes qui utiliseront votre API pour créer quelque chose ou simplement consommer des données. Votre API doit donc être aussi propre et intuitive que possible. Une API bien conçue est très facile à utiliser et à apprendre. C'est aussi intuitif, un bon point à garder à l'esprit lorsque vous commencez à concevoir votre API.

Nous utilisons REST pour créer des API depuis longtemps. Parallèlement à cela, il y a des problèmes. Lors de la création d'une API à l'aide de la conception REST, vous rencontrez des problèmes tels que:

1) vous aurez beaucoup de points de terminaison

2) Il sera beaucoup plus difficile pour les développeurs d'apprendre et de comprendre votre API

3) il y a sur et sous-extraction d'informations

Pour résoudre ces problèmes, Facebook a créé GraphQL. Aujourd'hui, je pense que GraphQL est le meilleur moyen de créer des API. Cet article vous expliquera pourquoi vous devriez commencer à l'apprendre dès aujourd'hui.

Dans cet article, vous allez apprendre comment fonctionne GraphQL. Je vais vous montrer comment créer une API très bien conçue, efficace et puissante en utilisant GraphQL.

Vous avez probablement déjà entendu parler de GraphQL, car de nombreuses personnes et entreprises l'utilisent. Depuis GraphQL est open-source, sa communauté est devenue énorme.

Il est maintenant temps pour vous de commencer à apprendre en pratique comment fonctionne GraphQL et tout sur sa magie.

Qu'est-ce que GraphQL?

GraphQL est un langage de requête open-source développé par Facebook. Cela nous permet de concevoir, créer et consommer nos API de manière plus efficace. En gros, c'est le remplacement de REST.

GraphQL a beaucoup de fonctionnalités, comme:

  1. Vous écrivez les données que vous voulez et vous obtenez exactement les données que vous voulez. Plus de surexploration d'informations comme nous en avons l'habitude avec REST.
  2. Cela nous donne un seul point de terminaison , plus de version 2 ou de version 3 pour la même API.
  3. GraphQL est fortement typé , et avec cela, vous pouvez valider une requête dans le système de type GraphQL avant son exécution. Cela nous aide à créer des API plus puissantes.

Ceci est une introduction de base à GraphQL - pourquoi il est si puissant et pourquoi il gagne en popularité ces jours-ci. Si vous souhaitez en savoir plus, je vous recommande d'aller sur le site Web de GraphQL et de le consulter.

Commencer

L'objectif principal de cet article n'est pas d'apprendre à configurer un serveur GraphQL, nous n'allons donc pas approfondir cela pour l'instant. L'objectif est d'apprendre comment GraphQL fonctionne dans la pratique, nous allons donc utiliser un serveur GraphQL sans configuration appelé ☄️ Graphpack.

Pour démarrer notre projet, nous allons créer un nouveau dossier et vous pouvez le nommer comme vous le souhaitez. Je vais l'appeler graphql-server:

Ouvrez votre terminal et tapez:

mkdir graphql-server

Maintenant, vous devriez avoir npm ou yarn installé dans votre machine. Si vous ne savez pas ce que c'est, npm et yarn sont des gestionnaires de packages pour le langage de programmation JavaScript. Pour Node.js, le gestionnaire de packages par défaut est npm .

Dans votre dossier créé, tapez la commande suivante:

npm init -y

Ou si vous utilisez du fil:

yarn init 

npm créera un package.jsonfichier pour vous, et toutes les dépendances que vous avez installées et vos commandes seront là.

Alors maintenant, nous allons installer la seule dépendance que nous allons utiliser.

☄️Graphpack vous permet de créer un serveur GraphQL sans configuration . Puisque nous ne faisons que commencer avec GraphQL, cela nous aidera beaucoup à continuer et à en savoir plus sans nous soucier de la configuration d'un serveur.

Dans votre terminal, dans votre dossier racine, installez-le comme ceci:

npm install --save-dev graphpack

Ou, si vous utilisez du fil, vous devriez procéder comme suit:

yarn add --dev graphpack

Une fois Graphpack installé, accédez à nos scripts dans le package.jsonfichier et placez-y le code suivant:

"scripts": { "dev": "graphpack", "build": "graphpack build" }

Nous allons créer un dossier appelé src, et ce sera le seul dossier de tout notre serveur.

Créez un dossier appelé src, après cela, dans notre dossier, nous allons créer trois fichiers uniquement.

Dans notre srcdossier, créez un fichier appelé schema.graphql. Dans ce premier fichier, mettez le code suivant:

type Query { hello: String }

Dans ce schema.graphqlfichier se trouvera tout notre schéma GraphQL. Si vous ne savez pas ce que c'est, je vous expliquerai plus tard - ne vous inquiétez pas.

Maintenant, dans notre srcdossier, créez un deuxième fichier. Appelez-le resolvers.jset, dans ce deuxième fichier, mettez le code suivant:

import { users } from "./db"; const resolvers = { Query: { hello: () => "Hello World!" } }; export default resolvers;

Ce resolvers.jsfichier va être la façon dont nous fournissons les instructions pour transformer une opération GraphQL en données.

Et enfin, dans votre srcdossier, créez un troisième fichier. Appelez ceci db.jset, dans ce troisième fichier, mettez le code suivant:

export let users = [ { id: 1, name: "John Doe", email: "[email protected]", age: 22 }, { id: 2, name: "Jane Doe", email: "[email protected]", age: 23 } ];

In this tutorial we’re not using a real-world database. So this db.js file is going to simulate a database, just for learning purposes.

Now our src folder should look like this:

src |--db.js |--resolvers.js |--schema.graphql

Now, if you run the command npm run dev or, if you’re using yarn, yarn dev, you should see this output in your terminal:

You can now go to localhost:4000 . This means that we’re ready to go and start writing our first queries, mutations, and subscriptions in GraphQL.

You see the GraphQL Playground, a powerful GraphQL IDE for better development workflows. If you want to learn more about GraphQL Playground, click here.

Schema

GraphQL has its own type of language that’s used to write schemas. This is a human-readable schema syntax called Schema Definition Language (SDL). The SDL will be the same, no matter what technology you’re using — you can use this with any language or framework that you want.

This schema language its very helpful because it’s simple to understand what types your API is going to have. You can understand it just by looking right it.

Types

Types are one of the most important features of GraphQL. Types are custom objects that represent how your API is going to look. For example, if you’re building a social media application, your API should have types such as Posts, Users, Likes, Groups.

Types have fields, and these fields return a specific type of data. For example, we’re going to create a User type, we should have some name, email, and age fields. Type fields can be anything, and always return a type of data as Int, Float, String, Boolean, ID, a List of Object Types, or Custom Objects Types.

So now to write our first Type, go to your schema.graphql file and replace the type Query that is already there with the following:

type User { id: ID! name: String! email: String! age: Int }

Each User is going to have an ID, so we gave it an ID type. User is also going to have a name and email, so we gave it a String type, and an age, which we gave an Int type. Pretty simple, right?

But, what about those ! at the end of every line? The exclamation point means that the fields are non-nullable, which means that every field must return some data in each query. The only nullable field that we’re going to have in our User type will be age.

In GraphQL, you will deal with three main concepts:

  1. queries — the way you’re going to get data from the server.
  2. mutations — the way you’re going to modify data on the server and get updated data back (create, update, delete).
  3. subscriptions — the way you’re going to maintain a real-time connection with the server.

I’m going to explain all of them to you. Let’s start with Queries.

Queries

To explain this in a simple way, queries in GraphQL are how you’re going to get data. One of the most beautiful things about queries in GraphQL is that you are just going to get the exact data that you want. No more, no less. This has a huge positive impact in our API — no more over-fetching or under-fetching information as we had with REST APIs.

We’re going to create our first type Query in GraphQL. All our queries will end up inside this type. So to start, we’ll go to our schema.graphql and write a new type called Query:

type Query { users: [User!]! }

It’s very simple: the usersquery will return to us an array of one or more Users. It will not return null, because we put in the ! , which means it’s a non-nullable query. It should always return something.

But we could also return a specific user. For that we’re going to create a new query called user. Inside our Query type, put the following code:

user(id: ID!): User! 

Now our Query type should look like this:

type Query { users: [User!]! user(id: ID!): User! }

As you see, with queries in GraphQL we can also pass arguments. In this case, to query for a specific user, we’re going to pass its ID.

But, you may be wondering: how does GraphQL know where get the data? That’s why we should have a resolvers.js file. That file tells GraphQL how and where it's going to fetch the data.

First, go to our resolvers.js file and import the db.js that we just created a few moments ago. Your resolvers.js file should look like this:

import { users } from "./db"; const resolvers = { Query: { hello: () => "Hello World!" } }; export default resolvers;

Now, we’re going to create our first Query. Go to your resolvers.js file and replace the hello function. Now your Query type should look like this:

import { users } from "./db"; const resolvers = { Query: { user: (parent, { id }, context, info) => { return users.find(user => user.id === id); }, users: (parent, args, context, info) => { return users; } } }; export default resolvers;

Now, to explain how is it going to work:

Each query resolver has four arguments. In the user function, we’re going to pass id as an argument, and then return the specific user that matches the passed id. Pretty simple.

In the users function, we’re just going to return the users array that already exists. It’ll always return to us all of our users.

Now, we’re going to test if our queries are working fine. Go to localhost:4000 and put in the following code:

query { users { id name email age } }

It should return to you all of our users.

Or, if you want to return a specific user:

query { user(id: 1) { id name email age } }

Now, we’re going to start learning about mutations, one of the most important features in GraphQL.

Mutations

In GraphQL, mutations are the way you’re going to modify data on the server and get updated data back. You can think like the CUD (Create, Update, Delete) of REST.

We’re going to create our first type mutation in GraphQL, and all our mutations will end up inside this type. So, to start, go to our schema.graphql and write a new type called mutation:

type Mutation { createUser(id: ID!, name: String!, email: String!, age: Int): User! updateUser(id: ID!, name: String, email: String, age: Int): User! deleteUser(id: ID!): User! }

As you can see, we’re going to have three mutations:

createUser: we should pass an ID, name, email, and age. It should return a new user to us.

updateUser: we should pass an ID, and a new name, email, or age. It should return a new user to us.

deleteUser: we should pass an ID. It should return a new user to us.

Now, go to our resolvers.js file and below the Query object, create a new mutation object like this:

Mutation: { createUser: (parent, { id, name, email, age }, context, info) => { const newUser = { id, name, email, age }; users.push(newUser); return newUser; }, updateUser: (parent, { id, name, email, age }, context, info) => { let newUser = users.find(user => user.id === id); newUser.name = name; newUser.email = email; newUser.age = age; return newUser; }, deleteUser: (parent, { id }, context, info) => { const userIndex = users.findIndex(user => user.id === id); if (userIndex === -1) throw new Error("User not found."); const deletedUsers = users.splice(userIndex, 1); return deletedUsers[0]; } }

Now, our resolvers.js file should look like this:

import { users } from "./db"; const resolvers = { Query: { user: (parent, { id }, context, info) => { return users.find(user => user.id === id); }, users: (parent, args, context, info) => { return users; } }, Mutation: { createUser: (parent, { id, name, email, age }, context, info) => { const newUser = { id, name, email, age }; users.push(newUser); return newUser; }, updateUser: (parent, { id, name, email, age }, context, info) => { let newUser = users.find(user => user.id === id); newUser.name = name; newUser.email = email; newUser.age = age; return newUser; }, deleteUser: (parent, { id }, context, info) => { const userIndex = users.findIndex(user => user.id === id); if (userIndex === -1) throw new Error("User not found."); const deletedUsers = users.splice(userIndex, 1); return deletedUsers[0]; } } }; export default resolvers;

Now, we’re going to test if our mutations are working fine. Go to localhost:4000 and put in the following code:

mutation { createUser(id: 3, name: "Robert", email: "[email protected]", age: 21) { id name email age } }

It should return a new user to you. If you want to try making new mutations, I recommend you to try for yourself! Try to delete this same user that you created to see if it’s working fine.

Finally, we’re going to start learning about subscriptions, and why they are so powerful.

Subscriptions

As I said before, subscriptions are the way you’re going to maintain a real-time connection with a server. That means that whenever an event occurs in the server and whenever that event is called, the server will send the corresponding data to the client.

By working with subscriptions, you can keep your app updated to the latest changes between different users.

A basic subscription is like this:

subscription { users { id name email age } }

You will say it’s very similar to a query, and yes it is. But it works differently.

When something is updated in the server, the server will run the GraphQL query specified in the subscription, and send a newly updated result to the client.

We’re not going to work with subscriptions in this specific article, but if you want to read more about them click here.

Conclusion

As you have seen, GraphQL is a new technology that is really powerful. It gives us real power to build better and well-designed APIs. That’s why I recommend you start to learn it now. For me, it will eventually replace REST.

Thanks for reading the article.

Follow me on Twitter!

Follow me on GitHub!

I’m looking for a remote opportunity, so if have any I’d love to hear about it, so please contact me at my Twitter!