Version tl; dr

Dans l'un des articles précédents, nous avons discuté, en bref, qu'est-ce que c'est que d'utiliser l'API GitHub v3. Cette version est conçue pour être interfacée comme toute autre API REST. Il existe des points de terminaison pour chaque ressource dont vous avez besoin pour accéder et / ou modifier. Il y a des points de terminaison pour chaque utilisateur, chaque organisation, chaque référentiel et ainsi de suite. Par exemple, chaque utilisateur a son point de terminaison de l'API à Https: // API.github.com / utilisateurs / Vous pouvez essayer de remplacer votre nom d'utilisateur au lieu de et entrer l'URL dans un navigateur pour voir avec quoi l'API répond avec.

GitHub API V4, en revanche, utilise GraphQL où le QL signifie la langue de requête. GraphQL est une nouvelle façon de concevoir vos API. Tout comme il existe de nombreux services Web offerts en tant qu'API REST, pas seulement ceux proposés par GitHub, il existe de nombreux services Web qui vous permet de vous interfacer via GraphQL.

La différence la plus nette que vous remarquerez entre GraphQL et REST API est que GraphQL peut fonctionner à partir d'un seul point de terminaison de l'API. Dans le cas de GitHub API V4, ce point final est https: // API.github.com / graphql et c'est. Vous n'avez pas à vous soucier de l'ajout de longues chaînes à la fin d'un URI racine ou de fournir un paramètre de chaîne de requête pour des informations supplémentaires. Vous envoyez simplement un argument de type JSON à cette API, vous demandant uniquement les choses dont vous avez besoin, et vous obtiendrez une charge utile JSON avec exactement les mêmes informations que vous avez demandées. Vous n'avez pas à faire face au filtrage des informations indésirables ou à souffrir de frais généraux en raison de grandes réponses.

Qu'est-ce que l'API REST?

Eh bien, REST signifie le transfert d'état de représentation et l'API signifie Interface de programmation d'application. Une API REST, ou une API `` Resful '', est devenue la principale philosophie de conception derrière la plupart des applications de serveur client modernes. L'idée émerge de la nécessité de séparer divers composants d'une application comme l'interface utilisateur côté client et la logique côté serveur.

Ainsi, la session entre un client et un serveur est généralement apatride. Une fois que la page Web et les scripts connexes sont chargés, vous pouvez continuer à interagir avec eux et lorsque vous effectuez une action (comme appuyez sur un bouton Envoyer), une demande d'envoi est envoyée avec toutes les informations contextuelles dont le serveur Web a besoin pour traiter cette demande ( comme le nom d'utilisateur, les jetons, etc.). L'application passe d'un état à un autre mais sans besoin constant de connexion entre le client et le serveur.

REST définit un ensemble de contraintes entre le client et le serveur, et la communication ne peut se produire que sous ces contraintes. Par exemple, le repos sur HTTP utilise généralement le modèle CRUD, qui signifie Créer, lire, mettre à jour et supprimer des méthodes et HTTP comme Post, Get, Put et Supprimer vous aidez à effectuer ces opérations et ces opérations seules. Les anciennes techniques d'intrusion comme les injections SQL ne sont pas une possibilité avec quelque chose comme une API de repos serrée (bien que ce soit le repos n'est pas une panacée de sécurité).

Il aide également beaucoup les développeurs à l'interface utilisateur! Étant donné que tout ce que vous recevez d'une demande HTTP est typique d'un flux de texte (formaté en JSON, parfois), vous pouvez facilement implémenter une page Web pour les navigateurs ou une application (dans votre langue préférée) sans vous soucier de l'architecture côté serveur. Vous lisez la documentation de l'API pour des services comme Reddit, Twitter ou Facebook et vous pouvez écrire des extensions pour eux ou des clients tiers dans la langue de votre choix, car vous êtes garanti que le comportement de l'API sera toujours le même.

Inversement, le serveur ne se soucie pas de savoir si le frontal est écrit dans Go, Ruby ou Python. Que ce soit un navigateur, une application ou une CLI. Il «voit» la demande et répond de manière appropriée.

Qu'est-ce que GraphQL?

Comme pour tout dans le monde des ordinateurs, les API REST sont devenus plus grands et plus complexes et en même temps que les gens voulaient les implémenter et les consommer de manière plus rapide et plus simple. C'est pourquoi Facebook a eu l'idée de GraphQL, et l'ouvrait plus tard l'ouvrage. Le QL dans GraphQL signifie le langage de requête.

GraphQL permet aux clients de faire des demandes d'API très spécifiques, au lieu de passer des appels d'API rigides avec des paramètres et des réponses prédéfinies. C'est beaucoup plus simple car le serveur répond alors avec exactement les données que vous lui avez demandé, sans rien.

Jetez un œil à cette demande de repos et à sa réponse correspondante. Cette demande est destinée à afficher uniquement la biographie publique d'un utilisateur.

Demande: Obtenez une API https: //.github.com / utilisateurs /
Réponse:

"Connexion": "Octocat",
"ID": 583231,
"Node_id": "MDQ6VXNLCJU4MZIZMQ ==",
"avatar_url": "https: // avatars3.githubusercontent.com / u / 583231?v = 4 ",
"Gravatar_id": "",
"URL": "https: // api.github.com / utilisateurs / octocat ",
"html_url": "https: // github.com / octocat ",
"abonnés_url": "https: // api.github.com / utilisateurs / octocat / abonnés ",
"suivant_url": "https: // api.github.com / utilisateurs / octocat / suivant / autre_user ",
"gists_url": "https: // api.github.com / utilisateurs / octocat / gist / gist_id ",
"starred_url": "https: // api.github.com / utilisateurs / octocat / étoilé / propriétaire / repo ",
"abonnements_url": "https: // api.github.com / utilisateurs / octocat / abonnements ",
"organisations_url": "https: // api.github.com / utilisateurs / octocat / org ",
"repos_url": "https: // api.github.com / utilisateurs / octocat / repos ",
"events_url": "https: // api.github.com / utilisateurs / octocat / événements / confidentialité ",
"reçus_events_url": "https: // api.github.com / utilisateurs / octocat / reçus_events ",
"type": "utilisateur",
"site_admin": faux,
"Nom": "The Octocat",
"Compagnie": "Github",
"Blog": "http: // www.github.com / blog ",
"Emplacement": "San Francisco",
"Email": null,
"Hirable": null,
"bio": null,
"public_repos": 8,
"public_gists": 8,
"Followers": 2455,
"Suivre": 9,
"Created_at": "2011-01-25T18: 44: 36Z",
"Updated_at": "2018-11-22T16: 00: 23Z"

J'ai utilisé le nom d'utilisateur Octocat, mais vous pouvez le remplacer par le nom d'utilisateur de votre choix et utiliser Curl pour faire cette demande dans la ligne de commande ou le facteur si vous avez besoin d'une GUI. Bien que la demande était simple, pensez à toutes les informations supplémentaires que vous obtenez de cette réponse. Si vous deviez traiter les données d'un million de ces utilisateurs et filtrer toutes les données inutiles en utilisant, alors ce n'est pas efficace. Vous gaspillez la bande passante, la mémoire et le calcul pour obtenir, stocker et filtrer toutes les millions de paires de valeurs clés supplémentaires que vous n'aurez jamais

La structure de la réponse n'est pas non plus quelque chose que vous savez au préalable. Cette réponse JSON est équivalente à l'objet Dictionnaire dans Python, ou un objet en JavaScript. D'autres points de terminaison répondront avec des objets JSON qui peuvent être composés d'objets imbriqués, de liste imbriquée dans l'objet ou de toute combinaison arbitraire de types de données JSON, et vous devrez référer la documentation pour obtenir les spécificités. Lorsque vous traitez la demande, vous devez être conscient de ce format qui passe du point final au point final.

GraphQL ne s'appuie pas sur les verbes HTTP comme la publication, obtenez, mettez et supprimez pour effectuer des opérations CRUD sur le serveur. Au lieu de cela, il n'y a qu'un seul type de type de demande HTTP et endopint pour toutes les opérations liées à Crud. Dans le cas de GitHub, cela implique des demandes de type de type avec un seul point de terminaison https: // API.github.com / graphql

Étant une demande de poste, il peut emporter avec un corps de texte JSON à travers lequel seront nos opérations GraphQL. Ces opérations peuvent être de typa mettre en doute Si tout ce qu'il veut faire est de lire certaines informations, ou si ce peut être un mutation Dans le cas, les données doivent être modifiées.

Pour passer des appels API GraphQL, vous pouvez utiliser GraphQL Explorer de GitHub. Jetez un œil à ce graphique mettre en doute pour récupérer le même type de données (biographie publique d'un utilisateur) que nous l'avons fait ci-dessus en utilisant le repos.

Demande: post https: // API.github.com / graphql
mettre en doute
User (Login: "Ranvo")
bio


Réponse:

"données":
"utilisateur":
"bio": "passionnés de technologie et de science. Je suis dans toutes sortes de trucs sans rapport
serveurs à la physique quantique.\ r \ noccasionally, j'écris des articles de blog sur les intérêts ci-dessus."

Comme vous pouvez le voir, la réponse ne comprend que ce que vous avez demandé, c'est la biographie de l'utilisateur. Vous sélectionnez un utilisateur spécifique en passant le nom d'utilisateur (dans mon cas, c'est Ranvo) Et puis vous demandez la valeur d'un attribut de cet utilisateur, dans ce cas, cet attribut est bio. Le serveur API recherche les informations spécifiques exactes et répond avec cela et rien d'autre.

D'un autre côté, GraphQL vous permet également de faire une seule demande et d'extraire des informations qui vous auraient pris plusieurs demandes dans l'API REST traditionnelle. Rappelons que toutes les demandes GraphQL sont faites à un seul point de terminaison API. Prenons par exemple le cas d'utilisation où vous devez demander le serveur API GitHub pour la biographie de l'utilisateur et l'une de ses clés SSH. Il faudrait deux objets de requêtes.

Demandes de repos: obtenez une API https: //.github.com // /
Obtenez une API https: //.github.com //clés
Demande de graphQL: post https: // API.github.com / graphql /
mettre en doute
User (Login: "Ranvo")
bio
publicKeys (dernier: 1)
bords
Node
clé





Réponse GraphQL:

"données":
"utilisateur":
"bio": "passionnés de technologie et de science. Je suis dans toutes sortes de trucs sans rapport
serveurs à la physique quantique.\ r \ noccasionally, j'écris des articles de blog sur les intérêts ci-dessus.",
"publicKeys":
"bords": [

"nœud":
"Key": "SSH-ED25519 AAAAC3NZAC1LZDI1NTE5AAAAIH31MVJRYDZEH8OD8JVAFPRUIGL65SWILYKPEGBUNGOT"


]]

Il y a un objet imbriqué, mais si vous regardez votre demande, ils correspondent à peu près à votre demande afin que vous puissiez savoir et, en quelque sorte, façonnez la structure de la réponse que vous obtenez .

Conclusion

GraphQL est livré avec sa propre courbe d'apprentissage, qui est très raide, ou pas du tout du tout selon qui vous demandez. D'un point de vue objectif, je peux poser les faits suivants pour vous. Il est flexible comme vous l'avez vu ci-dessus, il est introspectif - c'est-à-dire que vous pouvez interroger l'API GraphQL sur l'API lui-même. Même si vous n'allez pas construire votre serveur API en utilisant, il est probable que vous deviez vous interface avec une API qui ne permet que GraphQL uniquement.

Vous pouvez en savoir un peu plus sur ses détails techniques ici et si vous souhaitez passer des appels API GraphQL à partir de votre poste de travail local, utilisez Graphiql.