Pratiquez des requêtes GraphQL avec l'API de l'état de JavaScript

Apprendre à créer des API GraphQL peut être assez difficile. Mais vous pouvez apprendre à utiliser les API GraphQL en 10 minutes! Et il se trouve que j'ai l'API parfaite pour cela: le tout nouvel état de code frais de VS de l'API GraphQL JavaScript.

L'enquête sur l'état de JavaScript est une enquête annuelle du paysage JavaScript. Nous le faisons depuis quatre ans maintenant, et l'édition la plus récente a atteint plus de 20 000 développeurs.

Nous nous sommes toujours appuyés sur Gatsby pour construire notre site de vitrine, mais jusqu'à cette année, nous nourrissions nos données à Gatsby sous la forme de fichiers YAML statiques générés par une sorte de magie arcanique connue pour les simples mortels sous le nom de «Elasticsearch».

Mais depuis que Gatsby fait caca toutes les sources de données qu'elle mange en tant que graphQL de toute façon, nous pensons que nous pourrions aussi bien ignorer l'intermédiaire et le nourrir directement GraphQL! Oui, je sais, cette métaphore devient plus grossière d'ici la seconde et je le regrette déjà. Mon point est: nous avons construit une API GraphQL interne pour nos données, et maintenant nous la rendons à la disposition de tout le monde afin que vous puissiez également exploiter facilement l'ensemble de données!

"Mais attendez", dites-vous. «J'ai passé toute ma vie à étudier la lame qui ne m'a pas laissé le temps d'apprendre GraphQL!» Ne vous inquiétez pas: c'est là que cet article entre en jeu.

Qu'est-ce que GraphQL?

À la base, GraphQL est une syntaxe qui vous permet de spécifier les données que vous souhaitez recevoir d'une API. Notez que j'ai dit l'API et non la base de données. Contrairement à SQL, une requête GraphQL ne va pas directement à votre base de données mais à votre point de terminaison API GraphQL qui, à son tour, peut se connecter à une base de données ou à toute autre source de données.

Le grand avantage de GraphQL sur des paradigmes plus anciens comme le repos est qu'il vous permet de demander ce que vous voulez. Par exemple:

 requête {
  user (id: "foo123") {
  nom
 }
}

Vous obtiendrait un objet utilisateur avec un seul champ de nom. Besoin également de l'e-mail? Faites juste:

 requête {
 user (id: "foo123") {
  nom
  e-mail
 }
}

Comme vous pouvez le voir, le champ utilisateur de cet exemple prend en charge un argument d'identification. Et maintenant, nous arrivons à la fonction la plus cool de GraphQL, nidification:

 requête {
 user (id: "foo123") {
  nom
  e-mail
    Posts { 
      titre
      corps
    }
  }
}

Ici, nous disons que nous voulons trouver les publications de l'utilisateur et charger leur titre et leur corps. La bonne chose à propos de GraphQL est que notre couche API peut faire le travail de déterminer comment récupérer ces informations supplémentaires dans ce format spécifique car nous ne parlons pas directement à la base de données, même s'il n'est pas stocké dans un format imbriqué à l'intérieur de notre base de données réelle.

Sebastian Scholl fait un travail merveilleux expliquant GraphQL comme si vous le rencontriez pour la première fois dans un mélangeur de cocktails.

Présentation du graphiql

Graphiql (note le «i» là-dedans) est le GraphQL IDE le plus courant, et c'est l'outil que nous utiliserons pour explorer l'état de l'API JavaScript. Vous pouvez le lancer dès maintenant sur graphiql.stateofjs.com et il se connectera automatiquement à notre point de terminaison (qui est api.stateofjs.com/graphql). L'interface utilisateur se compose de trois éléments principaux: le panneau d'explorateur, le constructeur de requête et les panneaux de résultats. Nous ajouterons plus tard les panneaux DOCS à cela, mais restons simples pour le moment.

L'onglet Explorer fait partie d'une version turbo-boosted de Graphiql développée et maintenue par OneGraph. Merci beaucoup de nous avoir aidés à l'intégrer. Assurez-vous de consulter leur exemple de dépôt si vous souhaitez déployer votre propre instance Graphiql.

Ne vous inquiétez pas, je ne vais pas vous faire écrire de code pour l'instant. Au lieu de cela, commençons à partir d'une requête GraphQL existante, comme celle correspondant à l'expérience du développeur avec React au cours des quatre dernières années.

Rappelez-vous comment j'ai dit que nous utilisions GraphQL en interne pour construire notre site? Non seulement nous exposons l'API, mais nous exposons également les requêtes elles-mêmes. Cliquez sur le bouton Little "Exporter", copiez la requête dans l'onglet "GraphQL", collez-le dans la fenêtre de Builder de requête de GraphiQL et cliquez sur le bouton "Play".

Si tout s'est déroulé comme prévu, vous devriez voir vos données apparaître dans le panneau de résultats. Prenons un moment pour analyser la requête.

 requête react_experientequery {
  Enquête (enquête: js) {
    outil (id: react) {
      identifiant
      entité {
        page d'accueil
        nom
        github {
          URL
        }
      }
      expérience {
        Allyears {
          année
          total
          achèvement {
            compter
            pourcentage
          }
          Sensibilisation InterestsSatisfaction {
            conscience
            intérêt
            satisfaction
          }
          seaux {
            identifiant
            compter
            pourcentage
          }
        }
      }
    }
  }
}

Vient d'abord le mot-clé de la requête qui définit le début de notre requête GraphQL, ainsi que le nom de la requête, React_ExperiesQuery. Les noms de requête sont facultatifs dans GraphQL, mais peuvent être utiles à des fins de débogage.

Nous avons ensuite notre premier champ, Survey, qui prend un argument d'enquête. (Nous avons également une enquête sur l'état de CSS, nous devions donc spécifier l'enquête en question.) Nous avons ensuite un champ d'outils qui prend un argument d'identification. Et tout ce qui a suivi est lié aux résultats de l'API pour cet outil spécifique. L'entité vous donne des informations sur l'outil spécifique sélectionné (par exemple React) tandis que l'expérience contient les données statistiques réelles.

Maintenant, plutôt que de continuer à passer par tous ces champs ici, je vais vous apprendre une petite astuce: la commande cliquez (ou contrôlez cliquer) l'un de ces champs dans Graphiql, et il affichera le panneau Docs. Félicitations, vous venez de voir un autre des astuces astucieuses de GraphQL, l'auto-documentation! Vous pouvez rédiger de la documentation directement dans votre définition d'API et GraphiQL le rendra à son tour disponible pour les utilisateurs finaux.

Changements de variables

Ajusterons un peu les choses: dans le constructeur de requête, remplacez «React» par «Vuejs» et vous devriez remarquer une autre chose cool GraphQL: l'achèvement automatique. Cela est très utile pour éviter de faire des erreurs ou de gagner du temps! Appuyez à nouveau sur «Play» et vous obtiendrez les mêmes données, mais pour Vue cette fois.

Utilisation de l'explorateur

Nous allons maintenant débloquer un autre outil de puissance GraphQL: l'explorateur. L'explorateur est essentiellement un arbre de toute votre API qui vous permet non seulement de visualiser sa structure, mais également de créer des requêtes sans écrire une seule ligne de code! Essayons donc de recréer notre requête React à l'aide de l'explorateur cette fois.

Tout d'abord, ouvrons un nouvel onglet de navigateur et chargeons Graphiql.StateOfjs.com pour recommencer. Cliquez sur le nœud d'enquête dans l'explorateur, et sous le nœud d'outil, cliquez sur «Play». Le champ ID de l'outil doit être automatiquement ajouté aux résultats et - en passant - c'est le bon moment pour modifier la valeur de l'argument par défaut («TypeScript») pour «réagir».

Ensuite, continuons à former. Si vous ajoutez une entité sans sous-champs, vous devriez voir une petite ligne rouge ondulée en dessous de vous permettant de vous faire savoir que vous devez également spécifier au moins un ou plusieurs sous-champs. Alors, ajoutons l'ID, le nom et la page d'accueil au minimum. Une autre astuce utile: vous pouvez automatiquement dire à Graphiql d'ajouter tous les sous-champs d'un champ en le cliquant sur le contrôle des options dans l'explorateur.

La prochaine étape est l'expérience. Continuez à ajouter des champs et des sous-champs jusqu'à ce que vous obteniez quelque chose qui approche de la requête que vous avez initialement copiée à partir du site de l'état de JavaScript. Tout élément que vous sélectionnez est réfléchi instantanément dans le panneau de créateur de requête. Voilà, vous venez d'écrire votre première requête GraphQL!

Filtrage des données

Vous avez peut-être remarqué un élément de filtres violets sous expérience. C'est en fait leur raison clé pour laquelle vous souhaitez utiliser notre API GraphQL plutôt que pour simplement parcourir notre site: toute agrégation fournie par l'API peut être filtrée par un certain nombre de facteurs, tels que le genre, la taille de l'entreprise, le salaire ou le pays du répondant.

Développez les filtres et sélectionnez Companysize puis EQ et Range_More_Than_1000. Vous venez de calculer la popularité de React parmi les grandes entreprises! Sélectionnez Range_1 à la place et vous pouvez désormais le comparer avec le même point de données entre les indépendants et les développeurs indépendants.

Il est important de noter que GraphQL définit uniquement les primitives de niveau de bas niveau, telles que les champs et les arguments, donc ces filtres EQ, dans, nin, etc., ne font pas partie de GraphQL lui-même, mais simplement des arguments que nous nous sommes définis lors de la configuration de l'API. Cela peut être beaucoup de travail au début, mais cela vous donne un contrôle total sur la façon dont les clients peuvent interroger votre API.

Conclusion

J'espère que vous avez vu que l'interrogation d'une API GraphQL n'est pas une grosse affaire, en particulier avec des outils impressionnants comme Graphiql pour vous aider à le faire. Maintenant, bien sûr, l'intégration des données GraphQL dans une application du monde réel est une autre affaire, mais cela est principalement dû à la complexité de la gestion des transferts de données entre le client et le serveur. La partie GraphQL elle-même est en fait assez facile!

Que vous espériez commencer avec GraphQL ou simplement en apprendre suffisamment pour interroger nos données et trouver de nouvelles idées incroyables, j'espère que ce guide sera avéré utile!

Et si vous êtes intéressé à participer à notre prochaine enquête (qui devrait être l'état de CSS 2020), assurez-vous de vous inscrire à notre liste de diffusion afin que vous puissiez être averti lorsque nous le lançons.

Référence de l'API de l'état de JavaScript

Vous pouvez trouver plus d'informations sur l'API (y compris les liens vers le point de terminaison réel et le repo GitHub) sur API.StateOfjs.com.

Voici un glossaire rapide des termes utilisés à l'intérieur de l'API de l'état de JS.

Champs de haut niveau

• Démographie: regroupe toutes les informations démographiques telles que le sexe, la taille de l'entreprise, le salaire, etc.
• Entité: donne accès à plus d'informations sur une «entité» spécifique (bibliothèque, framework, langage de programmation, etc.).
• Caractéristique: données d'utilisation pour une fonction JavaScript ou CSS spécifique.
• Caractéristiques: Idem, mais sur une gamme de fonctionnalités.
• Matrices: donne accès aux données utilisées pour remplir nos marques de chaleur transversales.
• Opinion: Données d'opinion pour une question spécifique (par exemple, «Pensez-vous que JavaScript se déplace dans la bonne direction?»).
• OtherTools: Données pour la section «Autres outils» (éditeurs de texte, navigateurs, bundlers, etc.).
• Ressources: données pour la section «Ressources» (sites, blogs, podcasts, etc.).
• Outil: expérimentez les données pour un outil spécifique (bibliothèque, framework, etc.).
• Outils: Idem, mais sur une gamme d'outils.
• OutilsRankings: classement (sensibilisation, intérêt, satisfaction) sur une gamme d'outils.

Champs communs

• Achèvement: Quelle proportion de répondants au sondage a répondu à une question donnée.
• Podets: le tableau contenant les données réelles.
• Année / Allyears: s'il faut obtenir les données d'une année d'enquête spécifique; ou un tableau contenant toutes les années.

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!